From 883e90d06efe3822ed4bbd92f7127a4d44950627 Mon Sep 17 00:00:00 2001
From: Eugene Yurtsev <eyurtsev@gmail.com>
Date: Wed, 19 Jun 2024 11:35:30 -0400
Subject: [PATCH] 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         | 14 +++++++++++++-
 libs/core/langchain_core/messages/ai.py            |  5 +++--
 libs/core/langchain_core/messages/human.py         |  5 +++--
 .../tests/unit_tests/runnables/test_runnable.py    | 14 +++++++-------
 4 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/libs/core/langchain_core/documents/base.py b/libs/core/langchain_core/documents/base.py
index c72bfa724f..ed6955d7e6 100644
--- a/libs/core/langchain_core/documents/base.py
+++ b/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."""
diff --git a/libs/core/langchain_core/messages/ai.py b/libs/core/langchain_core/messages/ai.py
index 0ab7d95ea1..b8ed32e5a2 100644
--- a/libs/core/langchain_core/messages/ai.py
+++ b/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] = []
diff --git a/libs/core/langchain_core/messages/human.py b/libs/core/langchain_core/messages/human.py
index 2dbfc1108d..b1711484c3 100644
--- a/libs/core/langchain_core/messages/human.py
+++ b/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"
diff --git a/libs/core/tests/unit_tests/runnables/test_runnable.py b/libs/core/tests/unit_tests/runnables/test_runnable.py
index 2672d17c5b..5a0cf6e16a 100644
--- a/libs/core/tests/unit_tests/runnables/test_runnable.py
+++ b/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": {