langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/rate_limiters.py

@@ -6,7 +6,6 @@ import abc
 import asyncio
 import threading
 import time
-from typing import Optional
 
 
 class BaseRateLimiter(abc.ABC):
@@ -22,11 +21,8 @@ class BaseRateLimiter(abc.ABC):
     Current limitations:
 
     - Rate limiting information is not surfaced in tracing or callbacks. This means
-      that the total time it takes to invoke a chat model will encompass both
-      the time spent waiting for tokens and the time spent making the request.
-
-
-    .. versionadded:: 0.2.24
+        that the total time it takes to invoke a chat model will encompass both
+        the time spent waiting for tokens and the time spent making the request.
     """
 
     @abc.abstractmethod
@@ -34,18 +30,18 @@ class BaseRateLimiter(abc.ABC):
         """Attempt to acquire the necessary tokens for the rate limiter.
 
         This method blocks until the required tokens are available if `blocking`
-        is set to True.
+        is set to `True`.
 
-        If `blocking` is set to False, the method will immediately return the result
+        If `blocking` is set to `False`, the method will immediately return the result
         of the attempt to acquire the tokens.
 
         Args:
-            blocking: If True, the method will block until the tokens are available.
-                If False, the method will return immediately with the result of
-                the attempt. Defaults to True.
+            blocking: If `True`, the method will block until the tokens are available.
+                If `False`, the method will return immediately with the result of
+                the attempt.
 
         Returns:
-           True if the tokens were successfully acquired, False otherwise.
+            `True` if the tokens were successfully acquired, `False` otherwise.
         """
 
     @abc.abstractmethod
@@ -53,18 +49,18 @@ class BaseRateLimiter(abc.ABC):
         """Attempt to acquire the necessary tokens for the rate limiter.
 
         This method blocks until the required tokens are available if `blocking`
-        is set to True.
+        is set to `True`.
 
-        If `blocking` is set to False, the method will immediately return the result
+        If `blocking` is set to `False`, the method will immediately return the result
         of the attempt to acquire the tokens.
 
         Args:
-            blocking: If True, the method will block until the tokens are available.
-                If False, the method will return immediately with the result of
-                the attempt. Defaults to True.
+            blocking: If `True`, the method will block until the tokens are available.
+                If `False`, the method will return immediately with the result of
+                the attempt.
 
         Returns:
-           True if the tokens were successfully acquired, False otherwise.
+            `True` if the tokens were successfully acquired, `False` otherwise.
         """
 
 
@@ -85,45 +81,40 @@ class InMemoryRateLimiter(BaseRateLimiter):
     not enough tokens in the bucket, the request is blocked until there are
     enough tokens.
 
-    These *tokens* have NOTHING to do with LLM tokens. They are just
+    These tokens have nothing to do with LLM tokens. They are just
     a way to keep track of how many requests can be made at a given time.
 
     Current limitations:
 
     - The rate limiter is not designed to work across different processes. It is
-      an in-memory rate limiter, but it is thread safe.
+        an in-memory rate limiter, but it is thread safe.
     - The rate limiter only supports time-based rate limiting. It does not take
-      into account the size of the request or any other factors.
+        into account the size of the request or any other factors.
 
     Example:
+        ```python
+        import time
 
-        .. code-block:: python
-
-            import time
-
-            from langchain_core.rate_limiters import InMemoryRateLimiter
-
-            rate_limiter = InMemoryRateLimiter(
-                requests_per_second=0.1,  # <-- Can only make a request once every 10 seconds!!
-                check_every_n_seconds=0.1,  # Wake up every 100 ms to check whether allowed to make a request,
-                max_bucket_size=10,  # Controls the maximum burst size.
-            )
-
-            from langchain_anthropic import ChatAnthropic
-            model = ChatAnthropic(
-                model_name="claude-3-opus-20240229",
-                rate_limiter=rate_limiter
-            )
+        from langchain_core.rate_limiters import InMemoryRateLimiter
 
-            for _ in range(5):
-                tic = time.time()
-                model.invoke("hello")
-                toc = time.time()
-                print(toc - tic)
+        rate_limiter = InMemoryRateLimiter(
+            requests_per_second=0.1,  # <-- Can only make a request once every 10 seconds!!
+            check_every_n_seconds=0.1,  # Wake up every 100 ms to check whether allowed to make a request,
+            max_bucket_size=10,  # Controls the maximum burst size.
+        )
 
+        from langchain_anthropic import ChatAnthropic
 
-    .. versionadded:: 0.2.24
+        model = ChatAnthropic(
+            model_name="claude-sonnet-4-5-20250929", rate_limiter=rate_limiter
+        )
 
+        for _ in range(5):
+            tic = time.time()
+            model.invoke("hello")
+            toc = time.time()
+            print(toc - tic)
+        ```
     """  # noqa: E501
 
     def __init__(
@@ -135,7 +126,7 @@ class InMemoryRateLimiter(BaseRateLimiter):
     ) -> None:
         """A rate limiter based on a token bucket.
 
-        These *tokens* have NOTHING to do with LLM tokens. They are just
+        These tokens have nothing to do with LLM tokens. They are just
         a way to keep track of how many requests can be made at a given time.
 
         This rate limiter is designed to work in a threaded environment.
@@ -148,11 +139,11 @@ class InMemoryRateLimiter(BaseRateLimiter):
         Args:
             requests_per_second: The number of tokens to add per second to the bucket.
                 The tokens represent "credit" that can be used to make requests.
-            check_every_n_seconds: check whether the tokens are available
+            check_every_n_seconds: Check whether the tokens are available
                 every this many seconds. Can be a float to represent
                 fractions of a second.
             max_bucket_size: The maximum number of tokens that can be in the bucket.
-                Must be at least 1. Used to prevent bursts of requests.
+                Must be at least `1`. Used to prevent bursts of requests.
         """
         # Number of requests that we can make per second.
         self.requests_per_second = requests_per_second
@@ -163,7 +154,7 @@ class InMemoryRateLimiter(BaseRateLimiter):
         # at a given time.
         self._consume_lock = threading.Lock()
         # The last time we tried to consume tokens.
-        self.last: Optional[float] = None
+        self.last: float | None = None
         self.check_every_n_seconds = check_every_n_seconds
 
     def _consume(self) -> bool:
@@ -202,18 +193,18 @@ class InMemoryRateLimiter(BaseRateLimiter):
         """Attempt to acquire a token from the rate limiter.
 
         This method blocks until the required tokens are available if `blocking`
-        is set to True.
+        is set to `True`.
 
-        If `blocking` is set to False, the method will immediately return the result
+        If `blocking` is set to `False`, the method will immediately return the result
         of the attempt to acquire the tokens.
 
         Args:
-            blocking: If True, the method will block until the tokens are available.
-                If False, the method will return immediately with the result of
-                the attempt. Defaults to True.
+            blocking: If `True`, the method will block until the tokens are available.
+                If `False`, the method will return immediately with the result of
+                the attempt.
 
         Returns:
-           True if the tokens were successfully acquired, False otherwise.
+            `True` if the tokens were successfully acquired, `False` otherwise.
         """
         if not blocking:
             return self._consume()
@@ -226,18 +217,18 @@ class InMemoryRateLimiter(BaseRateLimiter):
         """Attempt to acquire a token from the rate limiter. Async version.
 
         This method blocks until the required tokens are available if `blocking`
-        is set to True.
+        is set to `True`.
 
-        If `blocking` is set to False, the method will immediately return the result
+        If `blocking` is set to `False`, the method will immediately return the result
         of the attempt to acquire the tokens.
 
         Args:
-            blocking: If True, the method will block until the tokens are available.
-                If False, the method will return immediately with the result of
-                the attempt. Defaults to True.
+            blocking: If `True`, the method will block until the tokens are available.
+                If `False`, the method will return immediately with the result of
+                the attempt.
 
         Returns:
-           True if the tokens were successfully acquired, False otherwise.
+            `True` if the tokens were successfully acquired, `False` otherwise.
         """
         if not blocking:
             return self._consume()

langchain_core/retrievers.py

@@ -3,34 +3,18 @@
 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
 """
 
 from __future__ import annotations
 
-import warnings
 from abc import ABC, abstractmethod
 from inspect import signature
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 from pydantic import ConfigDict
 from typing_extensions import Self, TypedDict, override
 
-from langchain_core._api import deprecated
-from langchain_core.callbacks import Callbacks
+from langchain_core.callbacks.manager import AsyncCallbackManager, CallbackManager
 from langchain_core.documents import Document
 from langchain_core.runnables import (
     Runnable,
@@ -57,11 +41,11 @@ class LangSmithRetrieverParams(TypedDict, total=False):
 
     ls_retriever_name: str
     """Retriever name."""
-    ls_vector_store_provider: Optional[str]
+    ls_vector_store_provider: str | None
     """Vector store provider."""
-    ls_embedding_provider: Optional[str]
+    ls_embedding_provider: str | None
     """Embedding provider."""
-    ls_embedding_model: Optional[str]
+    ls_embedding_model: str | None
     """Embedding model."""
 
 
@@ -86,46 +70,46 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
 
     Example: A retriever that returns the first 5 documents from a list of documents
 
-        .. code-block:: python
+    ```python
+    from langchain_core.documents import Document
+    from langchain_core.retrievers import BaseRetriever
 
-            from langchain_core.documents import Document
-            from langchain_core.retrievers import BaseRetriever
+    class SimpleRetriever(BaseRetriever):
+        docs: list[Document]
+        k: int = 5
 
-            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]
 
-                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]
+        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
+    ```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
+    class TFIDFRetriever(BaseRetriever, BaseModel):
+        vectorizer: Any
+        docs: list[Document]
+        tfidf_array: Any
+        k: int = 4
 
-                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]]
+        class Config:
+            arbitrary_types_allowed = True
 
-    """  # noqa: E501
+        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]]
+    ```
+    """
 
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
@@ -133,15 +117,15 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
 
     _new_arg_supported: bool = False
     _expects_other_args: bool = False
-    tags: Optional[list[str]] = None
-    """Optional list of tags associated with the retriever. Defaults to None.
+    tags: list[str] | None = None
+    """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`.
     You can use these to eg identify a specific instance of a retriever with its
     use case.
     """
-    metadata: Optional[dict[str, Any]] = None
-    """Optional metadata associated with the retriever. Defaults to None.
+    metadata: dict[str, Any] | None = None
+    """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`.
     You can use these to eg identify a specific instance of a retriever with its
@@ -151,35 +135,6 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
     @override
     def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
-        # Version upgrade for old retrievers that implemented the public
-        # methods directly.
-        if cls.get_relevant_documents != BaseRetriever.get_relevant_documents:
-            warnings.warn(
-                "Retrievers must implement abstract `_get_relevant_documents` method"
-                " instead of `get_relevant_documents`",
-                DeprecationWarning,
-                stacklevel=4,
-            )
-            swap = cls.get_relevant_documents
-            cls.get_relevant_documents = (  # type: ignore[method-assign]
-                BaseRetriever.get_relevant_documents
-            )
-            cls._get_relevant_documents = swap  # type: ignore[method-assign]
-        if (
-            hasattr(cls, "aget_relevant_documents")
-            and cls.aget_relevant_documents != BaseRetriever.aget_relevant_documents
-        ):
-            warnings.warn(
-                "Retrievers must implement abstract `_aget_relevant_documents` method"
-                " instead of `aget_relevant_documents`",
-                DeprecationWarning,
-                stacklevel=4,
-            )
-            aswap = cls.aget_relevant_documents
-            cls.aget_relevant_documents = (  # type: ignore[method-assign]
-                BaseRetriever.aget_relevant_documents
-            )
-            cls._aget_relevant_documents = aswap  # type: ignore[method-assign]
         parameters = signature(cls._get_relevant_documents).parameters
         cls._new_arg_supported = parameters.get("run_manager") is not None
         if (
@@ -212,7 +167,7 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
 
     @override
     def invoke(
-        self, input: str, config: Optional[RunnableConfig] = None, **kwargs: Any
+        self, input: str, config: RunnableConfig | None = None, **kwargs: Any
     ) -> list[Document]:
         """Invoke the retriever to get relevant documents.
 
@@ -220,21 +175,17 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
 
         Args:
             input: The query string.
-            config: Configuration for the retriever. Defaults to None.
-            kwargs: Additional arguments to pass to the retriever.
+            config: Configuration for the retriever.
+            **kwargs: Additional arguments to pass to the retriever.
 
         Returns:
             List of relevant documents.
 
         Examples:
-
-        .. code-block:: python
-
-            retriever.invoke("query")
-
+        ```python
+        retriever.invoke("query")
+        ```
         """
-        from langchain_core.callbacks.manager import CallbackManager
-
         config = ensure_config(config)
         inheritable_metadata = {
             **(config.get("metadata") or {}),
@@ -276,7 +227,7 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
     async def ainvoke(
         self,
         input: str,
-        config: Optional[RunnableConfig] = None,
+        config: RunnableConfig | None = None,
         **kwargs: Any,
     ) -> list[Document]:
         """Asynchronously invoke the retriever to get relevant documents.
@@ -285,21 +236,17 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
 
         Args:
             input: The query string.
-            config: Configuration for the retriever. Defaults to None.
-            kwargs: Additional arguments to pass to the retriever.
+            config: Configuration for the retriever.
+            **kwargs: Additional arguments to pass to the retriever.
 
         Returns:
             List of relevant documents.
 
         Examples:
-
-        .. code-block:: python
-
-            await retriever.ainvoke("query")
-
+        ```python
+        await retriever.ainvoke("query")
+        ```
         """
-        from langchain_core.callbacks.manager import AsyncCallbackManager
-
         config = ensure_config(config)
         inheritable_metadata = {
             **(config.get("metadata") or {}),
@@ -359,6 +306,7 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
         Args:
             query: String to find relevant documents for
             run_manager: The callback handler to use
+
         Returns:
             List of relevant documents
         """
@@ -368,91 +316,3 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):
             query,
             run_manager=run_manager.get_sync(),
         )
-
-    @deprecated(since="0.1.46", alternative="invoke", removal="1.0")
-    def get_relevant_documents(
-        self,
-        query: str,
-        *,
-        callbacks: Callbacks = None,
-        tags: Optional[list[str]] = None,
-        metadata: Optional[dict[str, Any]] = None,
-        run_name: Optional[str] = None,
-        **kwargs: Any,
-    ) -> list[Document]:
-        """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.
-        """
-        config: RunnableConfig = {}
-        if callbacks:
-            config["callbacks"] = callbacks
-        if tags:
-            config["tags"] = tags
-        if metadata:
-            config["metadata"] = metadata
-        if run_name:
-            config["run_name"] = run_name
-        return self.invoke(query, config, **kwargs)
-
-    @deprecated(since="0.1.46", alternative="ainvoke", removal="1.0")
-    async def aget_relevant_documents(
-        self,
-        query: str,
-        *,
-        callbacks: Callbacks = None,
-        tags: Optional[list[str]] = None,
-        metadata: Optional[dict[str, Any]] = None,
-        run_name: Optional[str] = None,
-        **kwargs: Any,
-    ) -> list[Document]:
-        """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.
-        """
-        config: RunnableConfig = {}
-        if callbacks:
-            config["callbacks"] = callbacks
-        if tags:
-            config["tags"] = tags
-        if metadata:
-            config["metadata"] = metadata
-        if run_name:
-            config["run_name"] = run_name
-        return await self.ainvoke(query, config, **kwargs)