core[patch]: Add an example to the Document schema doc-string (#23131)

Add an example to the document schema

libs/core/langchain_core/documents/base.py

@@ -7,7 +7,19 @@ from langchain_core.pydantic_v1 import Field
 
 
 class Document(Serializable):
-    """Class for storing a piece of text and associated metadata."""
+    """Class for storing a piece of text and associated metadata.
+
+    Example:
+
+        .. code-block:: python
+
+            from langchain_core.documents import Document
+
+            document = Document(
+                page_content="Hello, world!",
+                metadata={"source": "https://example.com"}
+            )
+    """
 
     page_content: str
     """String text."""

libs/core/langchain_core/messages/ai.py

@@ -40,8 +40,9 @@ class AIMessage(BaseMessage):
     """Message from an AI."""
 
     example: bool = False
-    """Whether this Message is being passed in to the model as part of an example 
-        conversation.
+    """Use to denote that a message is part of an example conversation.
+    
+    At the moment, this is ignored by most models. Usage is discouraged.
     """
 
     tool_calls: List[ToolCall] = []

libs/core/langchain_core/messages/human.py

@@ -7,8 +7,9 @@ class HumanMessage(BaseMessage):
     """Message from a human."""
 
     example: bool = False
-    """Whether this Message is being passed in to the model as part of an example 
-        conversation.
+    """Use to denote that a message is part of an example conversation.
+    
+    At the moment, this is ignored by most models. Usage is discouraged.
     """
 
     type: Literal["human"] = "human"

libs/core/tests/unit_tests/runnables/test_runnable.py

@@ -306,7 +306,7 @@ def test_schemas(snapshot: SnapshotAssertion) -> None:
         "definitions": {
             "Document": {
                 "title": "Document",
-                "description": "Class for storing a piece of text and associated metadata.",  # noqa: E501
+                "description": AnyStr(),
                 "type": "object",
                 "properties": {
                     "page_content": {"title": "Page Content", "type": "string"},
@@ -396,7 +396,7 @@ def test_schemas(snapshot: SnapshotAssertion) -> None:
             },
             "AIMessage": {
                 "title": "AIMessage",
-                "description": "Message from an AI.",
+                "description": AnyStr(),
                 "type": "object",
                 "properties": {
                     "content": {
@@ -450,7 +450,7 @@ def test_schemas(snapshot: SnapshotAssertion) -> None:
             },
             "HumanMessage": {
                 "title": "HumanMessage",
-                "description": "Message from a human.",
+                "description": AnyStr(),
                 "type": "object",
                 "properties": {
                     "content": {
@@ -491,7 +491,7 @@ def test_schemas(snapshot: SnapshotAssertion) -> None:
             },
             "ChatMessage": {
                 "title": "ChatMessage",
-                "description": "Message that can be assigned an arbitrary speaker (i.e. role).",  # noqa: E501
+                "description": AnyStr(),
                 "type": "object",
                 "properties": {
                     "content": {
@@ -528,7 +528,7 @@ def test_schemas(snapshot: SnapshotAssertion) -> None:
             },
             "SystemMessage": {
                 "title": "SystemMessage",
-                "description": "Message for priming AI behavior, usually passed in as the first of a sequence\nof input messages.",  # noqa: E501
+                "description": AnyStr(),
                 "type": "object",
                 "properties": {
                     "content": {
@@ -564,7 +564,7 @@ def test_schemas(snapshot: SnapshotAssertion) -> None:
             },
             "FunctionMessage": {
                 "title": "FunctionMessage",
-                "description": "Message for passing the result of executing a function back to a model.",  # noqa: E501
+                "description": AnyStr(),
                 "type": "object",
                 "properties": {
                     "content": {
@@ -600,7 +600,7 @@ def test_schemas(snapshot: SnapshotAssertion) -> None:
             },
             "ToolMessage": {
                 "title": "ToolMessage",
-                "description": "Message for passing the result of executing a tool back to a model.",  # noqa: E501
+                "description": AnyStr(),
                 "type": "object",
                 "properties": {
                     "content": {