core[patch]: Update documentation in LLM namespace (#23138)

Update documentation in lllm namespace.

libs/core/langchain_core/language_models/__init__.py

@@ -1,25 +1,40 @@
 """**Language Model** is a type of model that can generate text or complete
 text prompts. 
 
-LangChain has two main classes to work with language models:
+LangChain has two main classes to work with language models: **Chat Models** 
-- **LLM** classes provide access to the large language model (**LLM**) APIs and services.
+and "old-fashioned" **LLMs**.
-- **Chat Models** are a variation on language models.
 
-**Class hierarchy:**
+## Chat Models
 
-.. code-block::
+Language models that use a sequence of messages as inputs and return chat messages 
+as outputs (as opposed to using plain text). These are traditionally newer models (
+older models are generally LLMs, see below). Chat models support the assignment of 
+distinct roles to conversation messages, helping to distinguish messages from the AI, 
+users, and instructions such as system messages.
 
-    BaseLanguageModel --> BaseLLM --> LLM --> <name>  # Examples: AI21, HuggingFaceHub, OpenAI
+The key abstraction for chat models is `BaseChatModel`. Implementations
-                      --> BaseChatModel --> <name>    # Examples: ChatOpenAI, ChatGooglePalm
+should inherit from this class. Please see LangChain how-to guides with more
+information on how to implement a custom chat model.
 
-**Main helpers:**
+To implement a custom Chat Model, inherit from `BaseChatModel`. See
+the following guide for more information on how to implement a custom Chat Model:
 
-.. code-block::
+https://python.langchain.com/v0.2/docs/how_to/custom_chat_model/
 
-    LLMResult, PromptValue,
+## LLMs
-    CallbackManagerForLLMRun, AsyncCallbackManagerForLLMRun,
+
-    CallbackManager, AsyncCallbackManager,
+Language models that takes a string as input and returns a string. 
-    AIMessage, BaseMessage, HumanMessage
+These are traditionally older models (newer models generally are Chat Models, see below).
+
+Although the underlying models are string in, string out, the LangChain wrappers 
+also allow these models to take messages as input. This gives them the same interface 
+as Chat Models. When messages are passed in as input, they will be formatted into a 
+string under the hood before being passed to the underlying model.
+
+To implement a custom LLM, inherit from `BaseLLM` or `LLM`. 
+Please see the following guide for more information on how to implement a custom LLM:
+
+https://python.langchain.com/v0.2/docs/how_to/custom_llm/
 """  # noqa: E501
 
 from langchain_core.language_models.base import (

libs/core/langchain_core/language_models/chat_models.py

@@ -115,7 +115,26 @@ async def agenerate_from_stream(
 
 
 class BaseChatModel(BaseLanguageModel[BaseMessage], ABC):
-    """Base class for Chat models."""
+    """Base class for Chat models.
+
+    Custom chat model implementations should inherit from this class.
+
+    Follow the guide for more information on how to implement a
+    custom Chat Model:
+    [Guide](https://python.langchain.com/v0.2/docs/how_to/custom_chat_model/).
+
+    Please reference the table below for information about which
+    methods and properties are required or optional for implementations.
+
+    | Method/Property                  | Description                                                        | Required/Optional |
+    |----------------------------------|--------------------------------------------------------------------|-------------------|
+    | `_generate`                      | Use to generate a chat result from a prompt                        | Required          |
+    | `_llm_type` (property)           | Used to uniquely identify the type of the model. Used for logging. | Required          |
+    | `_identifying_params` (property) | Represent model parameterization for tracing purposes.             | Optional          |
+    | `_stream`                        | Use to implement streaming                                         | Optional          |
+    | `_agenerate`                     | Use to implement a native async method                             | Optional          |
+    | `_astream`                       | Use to implement async version of `_stream`                        | Optional          |
+    """  # noqa: E501
 
     callback_manager: Optional[BaseCallbackManager] = Field(default=None, exclude=True)
     """[DEPRECATED] Callback manager to add to the run trace."""
@@ -952,7 +971,11 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], ABC):
 
 
 class SimpleChatModel(BaseChatModel):
-    """Simplified implementation for a chat model to inherit from."""
+    """Simplified implementation for a chat model to inherit from.
+
+    **Note** This implementation is primarily here for backwards compatibility.
+        For new implementations, please use `BaseChatModel` directly.
+    """
 
     def _generate(
         self,

libs/core/langchain_core/language_models/fake.py

@@ -15,8 +15,19 @@ class FakeListLLM(LLM):
     """Fake LLM for testing purposes."""
 
     responses: List[str]
+    """List of responses to return in order."""
+    # This parameter should be removed from FakeListLLM since
+    # it's only used by sub-classes.
     sleep: Optional[float] = None
+    """Sleep time in seconds between responses.
+    
+    Ignored by FakeListLLM, but used by sub-classes.
+    """
     i: int = 0
+    """Internally incremented after every model invocation.
+    
+    Useful primarily for testing purposes.
+    """
 
     @property
     def _llm_type(self) -> str:
@@ -59,9 +70,16 @@ class FakeListLLM(LLM):
 
 
 class FakeStreamingListLLM(FakeListLLM):
-    """Fake streaming list LLM for testing purposes."""
+    """Fake streaming list LLM for testing purposes.
+
+    An LLM that will return responses from a list in order.
+
+    This model also supports optionally sleeping between successive
+    chunks in a streaming implementation.
+    """
 
     error_on_chunk_number: Optional[int] = None
+    """If set, will raise an exception on the specified chunk number."""
 
     def stream(
         self,

libs/core/langchain_core/language_models/fake_chat_models.py

@@ -17,8 +17,11 @@ class FakeMessagesListChatModel(BaseChatModel):
     """Fake ChatModel for testing purposes."""
 
     responses: List[BaseMessage]
+    """List of responses to **cycle** through in order."""
     sleep: Optional[float] = None
+    """Sleep time in seconds between responses."""
     i: int = 0
+    """Internally incremented after every model invocation."""
 
     def _generate(
         self,
@@ -43,10 +46,13 @@ class FakeMessagesListChatModel(BaseChatModel):
 class FakeListChatModel(SimpleChatModel):
     """Fake ChatModel for testing purposes."""
 
-    responses: List
+    responses: List[str]
+    """List of responses to **cycle** through in order."""
     sleep: Optional[float] = None
     i: int = 0
+    """List of responses to **cycle** through in order."""
     error_on_chunk_number: Optional[int] = None
+    """Internally incremented after every model invocation."""
 
     @property
     def _llm_type(self) -> str:

libs/core/langchain_core/language_models/llms.py

@@ -1240,6 +1240,11 @@ class LLM(BaseLLM):
         `astream` will use `_astream` if provided, otherwise it will implement
         a fallback behavior that will use `_stream` if `_stream` is implemented,
         and use `_acall` if `_stream` is not implemented.
+
+    Please see the following guide for more information on how to
+    implement a custom LLM:
+
+    https://python.langchain.com/v0.2/docs/how_to/custom_llm/
     """
 
     @abstractmethod