core[performance]: use custom __getattr__ in __init__.py files for lazy imports (#30769)

Most easily reviewed with the "hide whitespace" option toggled.

Seeing 10-50% speed ups in import time for common structures 🚀 

The general purpose of this PR is to lazily import structures within
`langchain_core.XXX_module.__init__.py` so that we're not eagerly
importing expensive dependencies (`pydantic`, `requests`, etc).

Analysis of flamegraphs generated with `importtime` motivated these
changes. For example, the one below demonstrates that importing
`HumanMessage` accidentally triggered imports for `importlib.metadata`,
`requests`, etc.

There's still much more to do on this front, and we can start digging
into our own internal code for optimizations now that we're less
concerned about external imports.

<img width="1210" alt="Screenshot 2025-04-11 at 1 10 54 PM"
src="https://github.com/user-attachments/assets/112a3fe7-24a9-4294-92c1-d5ae64df839e"
/>

I've tracked the improvements with some local benchmarks:

## `pytest-benchmark` results

| Name | Before (s) | After (s) | Delta (s) | % Change |

|-----------------------------|------------|-----------|-----------|----------|
| Document | 2.8683 | 1.2775 | -1.5908 | -55.46% |
| HumanMessage | 2.2358 | 1.1673 | -1.0685 | -47.79% |
| ChatPromptTemplate | 5.5235 | 2.9709 | -2.5526 | -46.22% |
| Runnable | 2.9423 | 1.7793 | -1.163 | -39.53% |
| InMemoryVectorStore | 3.1180 | 1.8417 | -1.2763 | -40.93% |
| RunnableLambda | 2.7385 | 1.8745 | -0.864 | -31.55% |
| tool | 5.1231 | 4.0771 | -1.046 | -20.42% |
| CallbackManager | 4.2263 | 3.4099 | -0.8164 | -19.32% |
| LangChainTracer | 3.8394 | 3.3101 | -0.5293 | -13.79% |
| BaseChatModel | 4.3317 | 3.8806 | -0.4511 | -10.41% |
| PydanticOutputParser | 3.2036 | 3.2995 | 0.0959 | 2.99% |
| InMemoryRateLimiter | 0.5311 | 0.5995 | 0.0684 | 12.88% |

Note the lack of change for `InMemoryRateLimiter` and
`PydanticOutputParser` is just random noise, I'm getting comparable
numbers locally.

## Local CodSpeed results

We're still working on configuring CodSpeed on CI. The local usage
produced similar results.

Author: sydney-runkle

libs/core/langchain_core/_api/__init__.py

@@ -9,20 +9,24 @@
 
 """
 
-from .beta_decorator import (
-    LangChainBetaWarning,
-    beta,
-    suppress_langchain_beta_warning,
-    surface_langchain_beta_warnings,
-)
-from .deprecation import (
-    LangChainDeprecationWarning,
-    deprecated,
-    suppress_langchain_deprecation_warning,
-    surface_langchain_deprecation_warnings,
-    warn_deprecated,
-)
-from .path import as_import_path, get_relative_path
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .beta_decorator import (
+        LangChainBetaWarning,
+        beta,
+        suppress_langchain_beta_warning,
+        surface_langchain_beta_warnings,
+    )
+    from .deprecation import (
+        LangChainDeprecationWarning,
+        deprecated,
+        suppress_langchain_deprecation_warning,
+        surface_langchain_deprecation_warnings,
+        warn_deprecated,
+    )
+    from .path import as_import_path, get_relative_path
 
 __all__ = [
     "as_import_path",
@@ -37,3 +41,33 @@
     "surface_langchain_deprecation_warnings",
     "warn_deprecated",
 ]
+
+_dynamic_imports = {
+    "LangChainBetaWarning": "beta_decorator",
+    "beta": "beta_decorator",
+    "suppress_langchain_beta_warning": "beta_decorator",
+    "surface_langchain_beta_warnings": "beta_decorator",
+    "as_import_path": "path",
+    "get_relative_path": "path",
+    "LangChainDeprecationWarning": "deprecation",
+    "deprecated": "deprecation",
+    "surface_langchain_deprecation_warnings": "deprecation",
+    "suppress_langchain_deprecation_warning": "deprecation",
+    "warn_deprecated": "deprecation",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    package = __spec__.parent  # type: ignore[name-defined]
+    if module_name == "__module__" or module_name is None:
+        result = import_module(f".{attr_name}", package=package)
+    else:
+        module = import_module(f".{module_name}", package=package)
+        result = getattr(module, attr_name)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

libs/core/langchain_core/callbacks/__init__.py

@@ -7,46 +7,50 @@
     BaseCallbackHandler --> <name>CallbackHandler  # Example: AimCallbackHandler
 """
 
-from langchain_core.callbacks.base import (
-    AsyncCallbackHandler,
-    BaseCallbackHandler,
-    BaseCallbackManager,
-    CallbackManagerMixin,
-    Callbacks,
-    ChainManagerMixin,
-    LLMManagerMixin,
-    RetrieverManagerMixin,
-    RunManagerMixin,
-    ToolManagerMixin,
-)
-from langchain_core.callbacks.file import FileCallbackHandler
-from langchain_core.callbacks.manager import (
-    AsyncCallbackManager,
-    AsyncCallbackManagerForChainGroup,
-    AsyncCallbackManagerForChainRun,
-    AsyncCallbackManagerForLLMRun,
-    AsyncCallbackManagerForRetrieverRun,
-    AsyncCallbackManagerForToolRun,
-    AsyncParentRunManager,
-    AsyncRunManager,
-    BaseRunManager,
-    CallbackManager,
-    CallbackManagerForChainGroup,
-    CallbackManagerForChainRun,
-    CallbackManagerForLLMRun,
-    CallbackManagerForRetrieverRun,
-    CallbackManagerForToolRun,
-    ParentRunManager,
-    RunManager,
-    adispatch_custom_event,
-    dispatch_custom_event,
-)
-from langchain_core.callbacks.stdout import StdOutCallbackHandler
-from langchain_core.callbacks.streaming_stdout import StreamingStdOutCallbackHandler
-from langchain_core.callbacks.usage import (
-    UsageMetadataCallbackHandler,
-    get_usage_metadata_callback,
-)
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_core.callbacks.base import (
+        AsyncCallbackHandler,
+        BaseCallbackHandler,
+        BaseCallbackManager,
+        CallbackManagerMixin,
+        Callbacks,
+        ChainManagerMixin,
+        LLMManagerMixin,
+        RetrieverManagerMixin,
+        RunManagerMixin,
+        ToolManagerMixin,
+    )
+    from langchain_core.callbacks.file import FileCallbackHandler
+    from langchain_core.callbacks.manager import (
+        AsyncCallbackManager,
+        AsyncCallbackManagerForChainGroup,
+        AsyncCallbackManagerForChainRun,
+        AsyncCallbackManagerForLLMRun,
+        AsyncCallbackManagerForRetrieverRun,
+        AsyncCallbackManagerForToolRun,
+        AsyncParentRunManager,
+        AsyncRunManager,
+        BaseRunManager,
+        CallbackManager,
+        CallbackManagerForChainGroup,
+        CallbackManagerForChainRun,
+        CallbackManagerForLLMRun,
+        CallbackManagerForRetrieverRun,
+        CallbackManagerForToolRun,
+        ParentRunManager,
+        RunManager,
+        adispatch_custom_event,
+        dispatch_custom_event,
+    )
+    from langchain_core.callbacks.stdout import StdOutCallbackHandler
+    from langchain_core.callbacks.streaming_stdout import StreamingStdOutCallbackHandler
+    from langchain_core.callbacks.usage import (
+        UsageMetadataCallbackHandler,
+        get_usage_metadata_callback,
+    )
 
 __all__ = [
     "dispatch_custom_event",
@@ -84,3 +88,56 @@
     "UsageMetadataCallbackHandler",
     "get_usage_metadata_callback",
 ]
+
+_dynamic_imports = {
+    "AsyncCallbackHandler": "base",
+    "BaseCallbackHandler": "base",
+    "BaseCallbackManager": "base",
+    "CallbackManagerMixin": "base",
+    "Callbacks": "base",
+    "ChainManagerMixin": "base",
+    "LLMManagerMixin": "base",
+    "RetrieverManagerMixin": "base",
+    "RunManagerMixin": "base",
+    "ToolManagerMixin": "base",
+    "FileCallbackHandler": "file",
+    "AsyncCallbackManager": "manager",
+    "AsyncCallbackManagerForChainGroup": "manager",
+    "AsyncCallbackManagerForChainRun": "manager",
+    "AsyncCallbackManagerForLLMRun": "manager",
+    "AsyncCallbackManagerForRetrieverRun": "manager",
+    "AsyncCallbackManagerForToolRun": "manager",
+    "AsyncParentRunManager": "manager",
+    "AsyncRunManager": "manager",
+    "BaseRunManager": "manager",
+    "CallbackManager": "manager",
+    "CallbackManagerForChainGroup": "manager",
+    "CallbackManagerForChainRun": "manager",
+    "CallbackManagerForLLMRun": "manager",
+    "CallbackManagerForRetrieverRun": "manager",
+    "CallbackManagerForToolRun": "manager",
+    "ParentRunManager": "manager",
+    "RunManager": "manager",
+    "adispatch_custom_event": "manager",
+    "dispatch_custom_event": "manager",
+    "StdOutCallbackHandler": "stdout",
+    "StreamingStdOutCallbackHandler": "streaming_stdout",
+    "UsageMetadataCallbackHandler": "usage",
+    "get_usage_metadata_callback": "usage",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    package = __spec__.parent  # type: ignore[name-defined]
+    if module_name == "__module__" or module_name is None:
+        result = import_module(f".{attr_name}", package=package)
+    else:
+        module = import_module(f".{module_name}", package=package)
+        result = getattr(module, attr_name)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

libs/core/langchain_core/document_loaders/__init__.py

@@ -1,8 +1,12 @@
 """Document loaders."""
 
-from langchain_core.document_loaders.base import BaseBlobParser, BaseLoader
-from langchain_core.document_loaders.blob_loaders import Blob, BlobLoader, PathLike
-from langchain_core.document_loaders.langsmith import LangSmithLoader
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_core.document_loaders.base import BaseBlobParser, BaseLoader
+    from langchain_core.document_loaders.blob_loaders import Blob, BlobLoader, PathLike
+    from langchain_core.document_loaders.langsmith import LangSmithLoader
 
 __all__ = [
     "BaseBlobParser",
@@ -12,3 +16,28 @@
     "PathLike",
     "LangSmithLoader",
 ]
+
+_dynamic_imports = {
+    "BaseBlobParser": "base",
+    "BaseLoader": "base",
+    "Blob": "blob_loaders",
+    "BlobLoader": "blob_loaders",
+    "PathLike": "blob_loaders",
+    "LangSmithLoader": "langsmith",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    package = __spec__.parent  # type: ignore[name-defined]
+    if module_name == "__module__" or module_name is None:
+        result = import_module(f".{attr_name}", package=package)
+    else:
+        module = import_module(f".{module_name}", package=package)
+        result = getattr(module, attr_name)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

libs/core/langchain_core/documents/__init__.py

@@ -5,8 +5,34 @@
 
 """
 
-from langchain_core.documents.base import Document
-from langchain_core.documents.compressor import BaseDocumentCompressor
-from langchain_core.documents.transformers import BaseDocumentTransformer
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import Document
+    from .compressor import BaseDocumentCompressor
+    from .transformers import BaseDocumentTransformer
 
 __all__ = ["Document", "BaseDocumentTransformer", "BaseDocumentCompressor"]
+
+_dynamic_imports = {
+    "Document": "base",
+    "BaseDocumentCompressor": "compressor",
+    "BaseDocumentTransformer": "transformers",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    package = __spec__.parent  # type: ignore[name-defined]
+    if module_name == "__module__" or module_name is None:
+        result = import_module(f".{attr_name}", package=package)
+    else:
+        module = import_module(f".{module_name}", package=package)
+        result = getattr(module, attr_name)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

libs/core/langchain_core/embeddings/__init__.py

@@ -1,6 +1,35 @@
 """Embeddings."""
 
-from langchain_core.embeddings.embeddings import Embeddings
-from langchain_core.embeddings.fake import DeterministicFakeEmbedding, FakeEmbeddings
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_core.embeddings.embeddings import Embeddings
+    from langchain_core.embeddings.fake import (
+        DeterministicFakeEmbedding,
+        FakeEmbeddings,
+    )
 
 __all__ = ["DeterministicFakeEmbedding", "Embeddings", "FakeEmbeddings"]
+
+_dynamic_imports = {
+    "Embeddings": "embeddings",
+    "DeterministicFakeEmbedding": "fake",
+    "FakeEmbeddings": "fake",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    package = __spec__.parent  # type: ignore[name-defined]
+    if module_name == "__module__" or module_name is None:
+        result = import_module(f".{attr_name}", package=package)
+    else:
+        module = import_module(f".{module_name}", package=package)
+        result = getattr(module, attr_name)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

libs/core/langchain_core/example_selectors/__init__.py

@@ -4,15 +4,19 @@
 This allows us to select examples that are most relevant to the input.
 """
 
-from langchain_core.example_selectors.base import BaseExampleSelector
-from langchain_core.example_selectors.length_based import (
-    LengthBasedExampleSelector,
-)
-from langchain_core.example_selectors.semantic_similarity import (
-    MaxMarginalRelevanceExampleSelector,
-    SemanticSimilarityExampleSelector,
-    sorted_values,
-)
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_core.example_selectors.base import BaseExampleSelector
+    from langchain_core.example_selectors.length_based import (
+        LengthBasedExampleSelector,
+    )
+    from langchain_core.example_selectors.semantic_similarity import (
+        MaxMarginalRelevanceExampleSelector,
+        SemanticSimilarityExampleSelector,
+        sorted_values,
+    )
 
 __all__ = [
     "BaseExampleSelector",
@@ -21,3 +25,27 @@
     "SemanticSimilarityExampleSelector",
     "sorted_values",
 ]
+
+_dynamic_imports = {
+    "BaseExampleSelector": "base",
+    "LengthBasedExampleSelector": "length_based",
+    "MaxMarginalRelevanceExampleSelector": "semantic_similarity",
+    "SemanticSimilarityExampleSelector": "semantic_similarity",
+    "sorted_values": "semantic_similarity",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    package = __spec__.parent  # type: ignore[name-defined]
+    if module_name == "__module__" or module_name is None:
+        result = import_module(f".{attr_name}", package=package)
+    else:
+        module = import_module(f".{module_name}", package=package)
+        result = getattr(module, attr_name)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)