langchain-core 1.0.0a8__py3-none-any.whl → 1.0.0rc1__py3-none-any.whl

langchain_core/utils/pydantic.py

@@ -78,7 +78,7 @@ def is_pydantic_v1_subclass(cls: type) -> bool:
     """Check if the given class is Pydantic v1-like.
 
     Returns:
-        True if the given class is a subclass of Pydantic ``BaseModel`` 1.x.
+        `True` if the given class is a subclass of Pydantic `BaseModel` 1.x.
     """
     return issubclass(cls, BaseModelV1)
 
@@ -87,7 +87,7 @@ def is_pydantic_v2_subclass(cls: type) -> bool:
     """Check if the given class is Pydantic v2-like.
 
     Returns:
-        True if the given class is a subclass of Pydantic BaseModel 2.x.
+        `True` if the given class is a subclass of Pydantic BaseModel 2.x.
     """
     return issubclass(cls, BaseModel)
 
@@ -101,7 +101,7 @@ def is_basemodel_subclass(cls: type) -> bool:
     * pydantic.v1.BaseModel in Pydantic 2.x
 
     Returns:
-        True if the given class is a subclass of Pydantic ``BaseModel``.
+        `True` if the given class is a subclass of Pydantic `BaseModel`.
     """
     # Before we can use issubclass on the cls we need to check if it is a class
     if not inspect.isclass(cls) or isinstance(cls, GenericAlias):
@@ -119,7 +119,7 @@ def is_basemodel_instance(obj: Any) -> bool:
     * pydantic.v1.BaseModel in Pydantic 2.x
 
     Returns:
-        True if the given class is an instance of Pydantic ``BaseModel``.
+        `True` if the given class is an instance of Pydantic `BaseModel`.
     """
     return isinstance(obj, (BaseModel, BaseModelV1))
 
@@ -129,10 +129,10 @@ def pre_init(func: Callable) -> Any:
     """Decorator to run a function before model initialization.
 
     Args:
-        func (Callable): The function to run before model initialization.
+        func: The function to run before model initialization.
 
     Returns:
-        Any: The decorated function.
+        The decorated function.
     """
     with warnings.catch_warnings():
         warnings.filterwarnings(action="ignore", category=PydanticDeprecationWarning)
@@ -146,11 +146,11 @@ def pre_init(func: Callable) -> Any:
             """Decorator to run a function before model initialization.
 
             Args:
-                cls (Type[BaseModel]): The model class.
-                values (dict[str, Any]): The values to initialize the model with.
+                cls: The model class.
+                values: The values to initialize the model with.
 
             Returns:
-                dict[str, Any]: The values to initialize the model with.
+                The values to initialize the model with.
             """
             # Insert default values
             fields = cls.model_fields
@@ -206,7 +206,7 @@ def _create_subset_model_v1(
     descriptions: dict | None = None,
     fn_description: str | None = None,
 ) -> type[BaseModel]:
-    """Create a pydantic model with only a subset of model's fields."""
+    """Create a Pydantic model with only a subset of model's fields."""
     fields = {}
 
     for field_name in field_names:
@@ -235,7 +235,7 @@ def _create_subset_model_v2(
     descriptions: dict | None = None,
     fn_description: str | None = None,
 ) -> type[BaseModel]:
-    """Create a pydantic model with a subset of the model fields."""
+    """Create a Pydantic model with a subset of the model fields."""
     descriptions_ = descriptions or {}
     fields = {}
     for field_name in field_names:
@@ -438,9 +438,9 @@ def create_model(
     /,
     **field_definitions: Any,
 ) -> type[BaseModel]:
-    """Create a pydantic model with the given field definitions.
+    """Create a Pydantic model with the given field definitions.
 
-    Please use create_model_v2 instead of this function.
+    Please use `create_model_v2` instead of this function.
 
     Args:
         model_name: The name of the model.
@@ -449,7 +449,7 @@ def create_model(
         **field_definitions: The field definitions for the model.
 
     Returns:
-        Type[BaseModel]: The created model.
+        The created model.
     """
     kwargs = {}
     if "__root__" in field_definitions:
@@ -511,7 +511,7 @@ def create_model_v2(
     field_definitions: dict[str, Any] | None = None,
     root: Any | None = None,
 ) -> type[BaseModel]:
-    """Create a pydantic model with the given field definitions.
+    """Create a Pydantic model with the given field definitions.
 
     Attention:
         Please do not use outside of langchain packages. This API
@@ -522,10 +522,10 @@ def create_model_v2(
         module_name: The name of the module where the model is defined.
             This is used by Pydantic to resolve any forward references.
         field_definitions: The field definitions for the model.
-        root: Type for a root model (RootModel)
+        root: Type for a root model (`RootModel`)
 
     Returns:
-        Type[BaseModel]: The created model.
+        The created model.
     """
     field_definitions = field_definitions or {}
 

langchain_core/utils/strings.py

@@ -10,7 +10,7 @@ def stringify_value(val: Any) -> str:
         val: The value to stringify.
 
     Returns:
-        str: The stringified value.
+        The stringified value.
     """
     if isinstance(val, str):
         return val
@@ -28,7 +28,7 @@ def stringify_dict(data: dict) -> str:
         data: The dictionary to stringify.
 
     Returns:
-        str: The stringified dictionary.
+        The stringified dictionary.
     """
     text = ""
     for key, value in data.items():
@@ -43,7 +43,7 @@ def comma_list(items: list[Any]) -> str:
         items: The list to convert.
 
     Returns:
-        str: The comma-separated string.
+        The comma-separated string.
     """
     return ", ".join(str(item) for item in items)
 
@@ -60,7 +60,7 @@ def sanitize_for_postgres(text: str, replacement: str = "") -> str:
         replacement: String to replace NUL bytes with. Defaults to empty string.
 
     Returns:
-        str: The sanitized text with NUL bytes removed or replaced.
+        The sanitized text with NUL bytes removed or replaced.
 
     Example:
         >>> sanitize_for_postgres("Hello\\x00world")

langchain_core/utils/utils.py

@@ -25,11 +25,11 @@ def xor_args(*arg_groups: tuple[str, ...]) -> Callable:
     """Validate specified keyword args are mutually exclusive.
 
     Args:
-        *arg_groups (tuple[str, ...]): Groups of mutually exclusive keyword args.
+        *arg_groups: Groups of mutually exclusive keyword args.
 
     Returns:
-        Callable: Decorator that validates the specified keyword args
-            are mutually exclusive.
+        Decorator that validates the specified keyword args
+        are mutually exclusive.
     """
 
     def decorator(func: Callable) -> Callable:
@@ -60,7 +60,7 @@ def raise_for_status_with_text(response: Response) -> None:
     """Raise an error with the response text.
 
     Args:
-        response (Response): The response to check for errors.
+        response: The response to check for errors.
 
     Raises:
         ValueError: If the response has an error status code.
@@ -79,11 +79,13 @@ def mock_now(dt_value: datetime.datetime) -> Iterator[type]:
         dt_value: The datetime value to use for datetime.now().
 
     Yields:
-        datetime.datetime: The mocked datetime class.
+        The mocked datetime class.
 
     Example:
-    with mock_now(datetime.datetime(2011, 2, 3, 10, 11)):
-        assert datetime.datetime.now() == datetime.datetime(2011, 2, 3, 10, 11)
+        ```python
+        with mock_now(datetime.datetime(2011, 2, 3, 10, 11)):
+            assert datetime.datetime.now() == datetime.datetime(2011, 2, 3, 10, 11)
+        ```
     """
 
     class MockDateTime(datetime.datetime):
@@ -120,14 +122,12 @@ def guard_import(
     Raise an exception if the module is not installed.
 
     Args:
-        module_name (str): The name of the module to import.
-        pip_name (str, optional): The name of the module to install with pip.
-            Defaults to None.
-        package (str, optional): The package to import the module from.
-            Defaults to None.
+        module_name: The name of the module to import.
+        pip_name: The name of the module to install with pip.
+        package: The package to import the module from.
 
     Returns:
-        Any: The imported module.
+        The imported module.
 
     Raises:
         ImportError: If the module is not installed.
@@ -154,15 +154,12 @@ def check_package_version(
     """Check the version of a package.
 
     Args:
-        package (str): The name of the package.
-        lt_version (str, optional): The version must be less than this.
-            Defaults to None.
-        lte_version (str, optional): The version must be less than or equal to this.
-            Defaults to None.
-        gt_version (str, optional): The version must be greater than this.
-            Defaults to None.
-        gte_version (str, optional): The version must be greater than or equal to this.
-            Defaults to None.
+        package: The name of the package.
+        lt_version: The version must be less than this.
+        lte_version: The version must be less than or equal to this.
+        gt_version: The version must be greater than this.
+        gte_version: The version must be greater than or equal to this.
+
 
     Raises:
         ValueError: If the package version does not meet the requirements.
@@ -201,7 +198,7 @@ def get_pydantic_field_names(pydantic_cls: Any) -> set[str]:
         pydantic_cls: Pydantic class.
 
     Returns:
-        set[str]: Field names.
+        Field names.
     """
     all_required_field_names = set()
     if is_pydantic_v1_subclass(pydantic_cls):
@@ -228,7 +225,7 @@ def _build_model_kwargs(
         all_required_field_names: All required field names for the pydantic class.
 
     Returns:
-        dict[str, Any]: Extra kwargs.
+        Extra kwargs.
 
     Raises:
         ValueError: If a field is specified in both values and extra_kwargs.
@@ -276,7 +273,7 @@ def build_extra_kwargs(
         all_required_field_names: All required field names for the pydantic class.
 
     Returns:
-        dict[str, Any]: Extra kwargs.
+        Extra kwargs.
 
     Raises:
         ValueError: If a field is specified in both values and extra_kwargs.
@@ -310,10 +307,10 @@ def convert_to_secret_str(value: SecretStr | str) -> SecretStr:
     """Convert a string to a SecretStr if needed.
 
     Args:
-        value (Union[SecretStr, str]): The value to convert.
+        value: The value to convert.
 
     Returns:
-        SecretStr: The SecretStr value.
+        The SecretStr value.
     """
     if isinstance(value, SecretStr):
         return value
@@ -501,7 +498,7 @@ Used for:
 def ensure_id(id_val: str | None) -> str:
     """Ensure the ID is a valid string, generating a new UUID if not provided.
 
-    Auto-generated UUIDs are prefixed by ``'lc_'`` to indicate they are
+    Auto-generated UUIDs are prefixed by `'lc_'` to indicate they are
     LangChain-generated IDs.
 
     Args:

langchain_core/vectorstores/base.py

@@ -3,21 +3,7 @@
 One of the most common ways to store and search over unstructured data is to
 embed it and store the resulting embedding vectors, and then query the store
 and retrieve the data that are 'most similar' to the embedded query.
-
-**Class hierarchy:**
-
-.. code-block::
-
-    VectorStore --> <name>  # Examples: Annoy, FAISS, Milvus
-
-    BaseRetriever --> VectorStoreRetriever --> <name>Retriever  # Example: VespaRetriever
-
-**Main helpers:**
-
-.. code-block::
-
-    Embeddings, Document
-"""  # noqa: E501
+"""
 
 from __future__ import annotations
 
@@ -123,12 +109,11 @@ class VectorStore(ABC):
         """Delete by vector ID or other criteria.
 
         Args:
-            ids: List of ids to delete. If None, delete all. Default is None.
+            ids: List of ids to delete. If `None`, delete all. Default is None.
             **kwargs: Other keyword arguments that subclasses might use.
 
         Returns:
-            Optional[bool]: True if deletion is successful,
-            False otherwise, None if not implemented.
+            True if deletion is successful, False otherwise, None if not implemented.
         """
         msg = "delete method must be implemented by subclass."
         raise NotImplementedError(msg)
@@ -191,12 +176,11 @@ class VectorStore(ABC):
         """Async delete by vector ID or other criteria.
 
         Args:
-            ids: List of ids to delete. If None, delete all. Default is None.
+            ids: List of ids to delete. If `None`, delete all. Default is None.
             **kwargs: Other keyword arguments that subclasses might use.
 
         Returns:
-            Optional[bool]: True if deletion is successful,
-            False otherwise, None if not implemented.
+            True if deletion is successful, False otherwise, None if not implemented.
         """
         return await run_in_executor(None, self.delete, ids, **kwargs)
 
@@ -255,7 +239,7 @@ class VectorStore(ABC):
 
         Args:
             documents: Documents to add to the vectorstore.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
                 if kwargs contains ids and documents contain ids,
                 the ids in the kwargs will receive precedence.
 
@@ -287,7 +271,7 @@ class VectorStore(ABC):
 
         Args:
             documents: Documents to add to the vectorstore.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
             List of IDs of the added texts.
@@ -815,10 +799,10 @@ class VectorStore(ABC):
         Args:
             documents: List of Documents to add to the vectorstore.
             embedding: Embedding function to use.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from documents and embeddings.
+            VectorStore initialized from documents and embeddings.
         """
         texts = [d.page_content for d in documents]
         metadatas = [d.metadata for d in documents]
@@ -845,10 +829,10 @@ class VectorStore(ABC):
         Args:
             documents: List of Documents to add to the vectorstore.
             embedding: Embedding function to use.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from documents and embeddings.
+            VectorStore initialized from documents and embeddings.
         """
         texts = [d.page_content for d in documents]
         metadatas = [d.metadata for d in documents]
@@ -882,10 +866,10 @@ class VectorStore(ABC):
             metadatas: Optional list of metadatas associated with the texts.
                 Default is None.
             ids: Optional list of IDs associated with the texts.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from texts and embeddings.
+            VectorStore initialized from texts and embeddings.
         """
 
     @classmethod
@@ -906,10 +890,10 @@ class VectorStore(ABC):
             metadatas: Optional list of metadatas associated with the texts.
                 Default is None.
             ids: Optional list of IDs associated with the texts.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from texts and embeddings.
+            VectorStore initialized from texts and embeddings.
         """
         if ids is not None:
             kwargs["ids"] = ids
@@ -930,12 +914,11 @@ class VectorStore(ABC):
         Args:
             **kwargs: Keyword arguments to pass to the search function.
                 Can include:
-                search_type (Optional[str]): Defines the type of search that
-                    the Retriever should perform.
-                    Can be "similarity" (default), "mmr", or
+                search_type: Defines the type of search that the Retriever should
+                    perform. Can be "similarity" (default), "mmr", or
                     "similarity_score_threshold".
-                search_kwargs (Optional[Dict]): Keyword arguments to pass to the
-                    search function. Can include things like:
+                search_kwargs: Keyword arguments to pass to the search function. Can
+                    include things like:
                         k: Amount of documents to return (Default: 4)
                         score_threshold: Minimum relevance threshold
                             for similarity_score_threshold
@@ -946,39 +929,35 @@ class VectorStore(ABC):
                         filter: Filter by document metadata
 
         Returns:
-            VectorStoreRetriever: Retriever class for VectorStore.
+            Retriever class for VectorStore.
 
         Examples:
+        ```python
+        # Retrieve more documents with higher diversity
+        # Useful if your dataset has many similar documents
+        docsearch.as_retriever(
+            search_type="mmr", search_kwargs={"k": 6, "lambda_mult": 0.25}
+        )
 
-        .. code-block:: python
-
-            # Retrieve more documents with higher diversity
-            # Useful if your dataset has many similar documents
-            docsearch.as_retriever(
-                search_type="mmr", search_kwargs={"k": 6, "lambda_mult": 0.25}
-            )
-
-            # Fetch more documents for the MMR algorithm to consider
-            # But only return the top 5
-            docsearch.as_retriever(
-                search_type="mmr", search_kwargs={"k": 5, "fetch_k": 50}
-            )
-
-            # Only retrieve documents that have a relevance score
-            # Above a certain threshold
-            docsearch.as_retriever(
-                search_type="similarity_score_threshold",
-                search_kwargs={"score_threshold": 0.8},
-            )
+        # Fetch more documents for the MMR algorithm to consider
+        # But only return the top 5
+        docsearch.as_retriever(search_type="mmr", search_kwargs={"k": 5, "fetch_k": 50})
 
-            # Only get the single most similar document from the dataset
-            docsearch.as_retriever(search_kwargs={"k": 1})
+        # Only retrieve documents that have a relevance score
+        # Above a certain threshold
+        docsearch.as_retriever(
+            search_type="similarity_score_threshold",
+            search_kwargs={"score_threshold": 0.8},
+        )
 
-            # Use a filter to only retrieve documents from a specific paper
-            docsearch.as_retriever(
-                search_kwargs={"filter": {"paper_title": "GPT-4 Technical Report"}}
-            )
+        # Only get the single most similar document from the dataset
+        docsearch.as_retriever(search_kwargs={"k": 1})
 
+        # Use a filter to only retrieve documents from a specific paper
+        docsearch.as_retriever(
+            search_kwargs={"filter": {"paper_title": "GPT-4 Technical Report"}}
+        )
+        ```
         """
         tags = kwargs.pop("tags", None) or [*self._get_retriever_tags()]
         return VectorStoreRetriever(vectorstore=self, tags=tags, **kwargs)
@@ -1012,7 +991,7 @@ class VectorStoreRetriever(BaseRetriever):
             values: Values to validate.
 
         Returns:
-            Values: Validated values.
+            Validated values.
 
         Raises:
             ValueError: If search_type is not one of the allowed search types.