From b64d846347d5dee6ced71a3711cc6981c267d2ee Mon Sep 17 00:00:00 2001
From: maang-h <55082429+maang-h@users.noreply.github.com>
Date: Tue, 10 Dec 2024 02:46:25 +0800
Subject: [PATCH] docs: Standardize MoonshotChat docstring (#28159)

- **Description:** Add docstring

Co-authored-by: Erick Friis <erick@langchain.dev>
---
 .../chat_models/moonshot.py                   | 139 ++++++++++++++++--
 1 file changed, 130 insertions(+), 9 deletions(-)

diff --git a/libs/community/langchain_community/chat_models/moonshot.py b/libs/community/langchain_community/chat_models/moonshot.py
index 7290c52b76e8b..68f8fdc5a5a28 100644
--- a/libs/community/langchain_community/chat_models/moonshot.py
+++ b/libs/community/langchain_community/chat_models/moonshot.py
@@ -13,21 +13,142 @@
 
 
 class MoonshotChat(MoonshotCommon, ChatOpenAI):  # type: ignore[misc, override, override]
-    """Moonshot large language models.
+    """Moonshot chat model integration.
 
-    To use, you should have the ``openai`` python package installed, and the
-    environment variable ``MOONSHOT_API_KEY`` set with your API key.
-    (Moonshot's chat API is compatible with OpenAI's SDK.)
+    Setup:
+        Install ``openai`` and set environment variables ``MOONSHOT_API_KEY``.
 
-    Referenced from https://platform.moonshot.cn/docs
+        .. code-block:: bash
 
-    Example:
+            pip install openai
+            export MOONSHOT_API_KEY="your-api-key"
+
+    Key init args — completion params:
+        model: str
+            Name of Moonshot model to use.
+        temperature: float
+            Sampling temperature.
+        max_tokens: Optional[int]
+            Max number of tokens to generate.
+
+    Key init args — client params:
+        api_key: Optional[str]
+            Moonshot API KEY. If not passed in will be read from env var MOONSHOT_API_KEY.
+        api_base: Optional[str]
+            Base URL for API requests.
+
+    See full list of supported init args and their descriptions in the params section.
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_community.chat_models import MoonshotChat
+
+            chat = MoonshotChat(
+                temperature=0.5,
+                api_key="your-api-key",
+                model="moonshot-v1-8k",
+                # api_base="...",
+                # other params...
+            )
+
+    Invoke:
+        .. code-block:: python
+
+            messages = [
+                ("system", "你是一名专业的翻译家，可以将用户的中文翻译为英文。"),
+                ("human", "我喜欢编程。"),
+            ]
+            chat.invoke(messages)
+
+        .. code-block:: python
+
+            AIMessage(
+                content='I like programming.',
+                additional_kwargs={},
+                response_metadata={
+                    'token_usage': {
+                        'completion_tokens': 5,
+                        'prompt_tokens': 27,
+                        'total_tokens': 32
+                    },
+                    'model_name': 'moonshot-v1-8k',
+                    'system_fingerprint': None,
+                    'finish_reason': 'stop',
+                    'logprobs': None
+                },
+                id='run-71c03f4e-6628-41d5-beb6-d2559ae68266-0'
+            )
+
+    Stream:
         .. code-block:: python
 
-            from langchain_community.chat_models.moonshot import MoonshotChat
+            for chunk in chat.stream(messages):
+                print(chunk)
+
+        .. code-block:: python
+
+            content='' additional_kwargs={} response_metadata={} id='run-80d77096-8b83-4c39-a84d-71d9c746da92'
+            content='I' additional_kwargs={} response_metadata={} id='run-80d77096-8b83-4c39-a84d-71d9c746da92'
+            content=' like' additional_kwargs={} response_metadata={} id='run-80d77096-8b83-4c39-a84d-71d9c746da92'
+            content=' programming' additional_kwargs={} response_metadata={} id='run-80d77096-8b83-4c39-a84d-71d9c746da92'
+            content='.' additional_kwargs={} response_metadata={} id='run-80d77096-8b83-4c39-a84d-71d9c746da92'
+            content='' additional_kwargs={} response_metadata={'finish_reason': 'stop'} id='run-80d77096-8b83-4c39-a84d-71d9c746da92'
+
+        .. code-block:: python
+
+            stream = chat.stream(messages)
+            full = next(stream)
+            for chunk in stream:
+                full += chunk
+            full
+
+        .. code-block:: python
+
+            AIMessageChunk(
+                content='I like programming.',
+                additional_kwargs={},
+                response_metadata={'finish_reason': 'stop'},
+                id='run-10c80976-7aa5-4ff7-ba3e-1251665557ef'
+            )
+
+    Async:
+        .. code-block:: python
+
+            await chat.ainvoke(messages)
+
+            # stream:
+            # async for chunk in chat.astream(messages):
+            #    print(chunk)
+
+            # batch:
+            # await chat.abatch([messages])
+
+        .. code-block:: python
+
+            [AIMessage(content='I like programming.', additional_kwargs={}, response_metadata={'token_usage': {'completion_tokens': 5, 'prompt_tokens': 27, 'total_tokens': 32}, 'model_name': 'moonshot-v1-8k', 'system_fingerprint': None, 'finish_reason': 'stop', 'logprobs': None}, id='run-2938b005-9204-4b9f-b273-1c3272fce9e5-0')]
+
+    Response metadata
+        .. code-block:: python
+
+            ai_msg = chat.invoke(messages)
+            ai_msg.response_metadata
+
+        .. code-block:: python
 
-            moonshot = MoonshotChat(model="moonshot-v1-8k")
-    """
+            {
+                'token_usage': {
+                    'completion_tokens': 5,
+                    'prompt_tokens': 27,
+                    'total_tokens': 32
+                },
+                'model_name': 'moonshot-v1-8k',
+                'system_fingerprint': None,
+                'finish_reason': 'stop',
+                'logprobs': None
+            }
+
+    """  # noqa: E501
 
     @pre_init
     def validate_environment(cls, values: Dict) -> Dict: