docs: update integration api refs (#25195)

- [x] toolkits
- [x] retrievers (in this repo)

libs/cli/langchain_cli/integration_template/integration_template/retrievers.py

@@ -44,7 +44,7 @@ class __ModuleName__Retriever(BaseRetriever):
 
             retriever.invoke(query)
 
-        .. code-block:: python
+        .. code-block:: none
 
             # TODO: Example output.
 
@@ -67,7 +67,7 @@ class __ModuleName__Retriever(BaseRetriever):
             llm = ChatOpenAI(model="gpt-3.5-turbo-0125")
 
             def format_docs(docs):
-                return "\n\n".join(doc.page_content for doc in docs)
+                return "\\n\\n".join(doc.page_content for doc in docs)
 
             chain = (
                 {"context": retriever | format_docs, "question": RunnablePassthrough()}
@@ -78,7 +78,7 @@ def format_docs(docs):
 
             chain.invoke("...")
 
-        .. code-block:: python
+        .. code-block:: none
 
              # TODO: Example output.
 

libs/cli/langchain_cli/integration_template/integration_template/toolkits.py

@@ -41,7 +41,7 @@ class __ModuleName__Toolkit(BaseToolKit):
 
             toolkit.get_tools()
 
-        .. code-block:: python
+        .. code-block:: none
 
             # TODO: Example output.
 
@@ -61,7 +61,7 @@ class __ModuleName__Toolkit(BaseToolKit):
             for event in events:
                 event["messages"][-1].pretty_print()
 
-        .. code-block:: python
+        .. code-block:: none
 
              # TODO: Example output.
 

libs/community/langchain_community/agent_toolkits/github/toolkit.py

@@ -164,9 +164,105 @@ class GitHubToolkit(BaseToolkit):
 
         See [Security](https://python.langchain.com/docs/security) for more information.
 
+    Setup:
+        See detailed installation instructions here:
+        https://python.langchain.com/v0.2/docs/integrations/tools/github/#installation
+
+        You will need to install ``pygithub`` and set the following environment
+        variables:
+
+        .. code-block:: bash
+
+            pip install -U pygithub
+            export GITHUB_APP_ID="your-app-id"
+            export GITHUB_APP_PRIVATE_KEY="path-to-private-key"
+            export GITHUB_REPOSITORY="your-github-repository"
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_community.agent_toolkits.github.toolkit import GitHubToolkit
+            from langchain_community.utilities.github import GitHubAPIWrapper
+
+            github = GitHubAPIWrapper()
+            toolkit = GitHubToolkit.from_github_api_wrapper(github)
+
+    Tools:
+        .. code-block:: python
+
+            tools = toolkit.get_tools()
+            for tool in tools:
+                print(tool.name)
+
+        .. code-block:: none
+
+            Get Issues
+            Get Issue
+            Comment on Issue
+            List open pull requests (PRs)
+            Get Pull Request
+            Overview of files included in PR
+            Create Pull Request
+            List Pull Requests' Files
+            Create File
+            Read File
+            Update File
+            Delete File
+            Overview of existing files in Main branch
+            Overview of files in current working branch
+            List branches in this repository
+            Set active branch
+            Create a new branch
+            Get files from a directory
+            Search issues and pull requests
+            Search code
+            Create review request
+
+    Use within an agent:
+        .. code-block:: python
+
+            from langchain_openai import ChatOpenAI
+            from langgraph.prebuilt import create_react_agent
+
+            # Select example tool
+            tools = [tool for tool in toolkit.get_tools() if tool.name == "Get Issue"]
+            assert len(tools) == 1
+            tools[0].name = "get_issue"
+
+            llm = ChatOpenAI(model="gpt-4o-mini")
+            agent_executor = create_react_agent(llm, tools)
+
+            example_query = "What is the title of issue 24888?"
+
+            events = agent_executor.stream(
+                {"messages": [("user", example_query)]},
+                stream_mode="values",
+            )
+            for event in events:
+                event["messages"][-1].pretty_print()
+
+        .. code-block:: none
+
+             ================================[1m Human Message [0m=================================
+
+            What is the title of issue 24888?
+            ==================================[1m Ai Message [0m==================================
+            Tool Calls:
+            get_issue (call_iSYJVaM7uchfNHOMJoVPQsOi)
+            Call ID: call_iSYJVaM7uchfNHOMJoVPQsOi
+            Args:
+                issue_number: 24888
+            =================================[1m Tool Message [0m=================================
+            Name: get_issue
+
+            {"number": 24888, "title": "Standardize KV-Store Docs", "body": "..."
+            ==================================[1m Ai Message [0m==================================
+
+            The title of issue 24888 is "Standardize KV-Store Docs".
+
     Parameters:
         tools: List[BaseTool]. The tools in the toolkit. Default is an empty list.
-    """
+    """  # noqa: E501
 
     tools: List[BaseTool] = []
 

libs/community/langchain_community/agent_toolkits/gmail/toolkit.py

@@ -39,9 +39,81 @@ class GmailToolkit(BaseToolkit):
 
         See https://python.langchain.com/docs/security for more information.
 
+    Setup:
+        You will need a Google credentials.json file to use this toolkit.
+        See instructions here: https://python.langchain.com/v0.2/docs/integrations/tools/gmail/#setup
+
+    Key init args:
+        api_resource: Optional. The Google API resource. Default is None.
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_google_community import GmailToolkit
+
+            toolkit = GmailToolkit()
+
+    Tools:
+        .. code-block:: python
+
+            toolkit.get_tools()
+
+        .. code-block:: none
+
+            [GmailCreateDraft(api_resource=<googleapiclient.discovery.Resource object at 0x1094509d0>),
+            GmailSendMessage(api_resource=<googleapiclient.discovery.Resource object at 0x1094509d0>),
+            GmailSearch(api_resource=<googleapiclient.discovery.Resource object at 0x1094509d0>),
+            GmailGetMessage(api_resource=<googleapiclient.discovery.Resource object at 0x1094509d0>),
+            GmailGetThread(api_resource=<googleapiclient.discovery.Resource object at 0x1094509d0>)]
+
+    Use within an agent:
+        .. code-block:: python
+
+            from langchain_openai import ChatOpenAI
+            from langgraph.prebuilt import create_react_agent
+
+            llm = ChatOpenAI(model="gpt-4o-mini")
+
+            agent_executor = create_react_agent(llm, tools)
+
+            example_query = "Draft an email to [email protected] thanking them for coffee."
+
+            events = agent_executor.stream(
+                {"messages": [("user", example_query)]},
+                stream_mode="values",
+            )
+            for event in events:
+                event["messages"][-1].pretty_print()
+
+        .. code-block:: none
+
+             ================================[1m Human Message [0m=================================
+
+            Draft an email to [email protected] thanking them for coffee.
+            ==================================[1m Ai Message [0m==================================
+            Tool Calls:
+            create_gmail_draft (call_slGkYKZKA6h3Mf1CraUBzs6M)
+            Call ID: call_slGkYKZKA6h3Mf1CraUBzs6M
+            Args:
+                message: Dear Fake,
+
+            I wanted to take a moment to thank you for the coffee yesterday. It was a pleasure catching up with you. Let's do it again soon!
+
+            Best regards,
+            [Your Name]
+                to: ['[email protected]']
+                subject: Thank You for the Coffee
+            =================================[1m Tool Message [0m=================================
+            Name: create_gmail_draft
+
+            Draft created. Draft Id: r-7233782721440261513
+            ==================================[1m Ai Message [0m==================================
+
+            I have drafted an email to [email protected] thanking them for the coffee. You can review and send it from your email draft with the subject "Thank You for the Coffee".
+
     Parameters:
         api_resource: Optional. The Google API resource. Default is None.
-    """
+    """  # noqa: E501
 
     api_resource: Resource = Field(default_factory=build_resource_service)
 

libs/community/langchain_community/agent_toolkits/openapi/toolkit.py

@@ -38,7 +38,125 @@ class RequestsToolkit(BaseToolkit):
         what network access it has.
 
         See https://python.langchain.com/docs/security for more information.
-    """
+
+    Setup:
+        Install ``langchain-community``.
+
+        .. code-block:: bash
+
+            pip install -U langchain-community
+
+    Key init args:
+        requests_wrapper: langchain_community.utilities.requests.GenericRequestsWrapper
+            wrapper for executing requests.
+        allow_dangerous_requests: bool
+            Defaults to False. Must "opt-in" to using dangerous requests by setting to True.
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_community.agent_toolkits.openapi.toolkit import RequestsToolkit
+            from langchain_community.utilities.requests import TextRequestsWrapper
+
+            toolkit = RequestsToolkit(
+                requests_wrapper=TextRequestsWrapper(headers={}),
+                allow_dangerous_requests=ALLOW_DANGEROUS_REQUEST,
+            )
+
+    Tools:
+        .. code-block:: python
+
+            tools = toolkit.get_tools()
+            tools
+
+        .. code-block:: none
+
+            [RequestsGetTool(requests_wrapper=TextRequestsWrapper(headers={}, aiosession=None, auth=None, response_content_type='text', verify=True), allow_dangerous_requests=True),
+            RequestsPostTool(requests_wrapper=TextRequestsWrapper(headers={}, aiosession=None, auth=None, response_content_type='text', verify=True), allow_dangerous_requests=True),
+            RequestsPatchTool(requests_wrapper=TextRequestsWrapper(headers={}, aiosession=None, auth=None, response_content_type='text', verify=True), allow_dangerous_requests=True),
+            RequestsPutTool(requests_wrapper=TextRequestsWrapper(headers={}, aiosession=None, auth=None, response_content_type='text', verify=True), allow_dangerous_requests=True),
+            RequestsDeleteTool(requests_wrapper=TextRequestsWrapper(headers={}, aiosession=None, auth=None, response_content_type='text', verify=True), allow_dangerous_requests=True)]
+
+    Use within an agent:
+        .. code-block:: python
+
+            from langchain_openai import ChatOpenAI
+            from langgraph.prebuilt import create_react_agent
+
+
+            api_spec = \"\"\"
+            openapi: 3.0.0
+            info:
+              title: JSONPlaceholder API
+              version: 1.0.0
+            servers:
+              - url: https://jsonplaceholder.typicode.com
+            paths:
+              /posts:
+                get:
+                  summary: Get posts
+                  parameters: &id001
+                    - name: _limit
+                      in: query
+                      required: false
+                      schema:
+                        type: integer
+                      example: 2
+                      description: Limit the number of results
+            \"\"\"
+
+            system_message = \"\"\"
+            You have access to an API to help answer user queries.
+            Here is documentation on the API:
+            {api_spec}
+            \"\"\".format(api_spec=api_spec)
+
+            llm = ChatOpenAI(model="gpt-4o-mini")
+            agent_executor = create_react_agent(llm, tools, state_modifier=system_message)
+
+            example_query = "Fetch the top two posts. What are their titles?"
+
+            events = agent_executor.stream(
+                {"messages": [("user", example_query)]},
+                stream_mode="values",
+            )
+            for event in events:
+                event["messages"][-1].pretty_print()
+
+        .. code-block:: none
+
+             ================================[1m Human Message [0m=================================
+
+            Fetch the top two posts. What are their titles?
+            ==================================[1m Ai Message [0m==================================
+            Tool Calls:
+            requests_get (call_RV2SOyzCnV5h2sm4WPgG8fND)
+            Call ID: call_RV2SOyzCnV5h2sm4WPgG8fND
+            Args:
+                url: https://jsonplaceholder.typicode.com/posts?_limit=2
+            =================================[1m Tool Message [0m=================================
+            Name: requests_get
+
+            [
+            {
+                "userId": 1,
+                "id": 1,
+                "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
+                "body": "quia et suscipit..."
+            },
+            {
+                "userId": 1,
+                "id": 2,
+                "title": "qui est esse",
+                "body": "est rerum tempore vitae..."
+            }
+            ]
+            ==================================[1m Ai Message [0m==================================
+
+            The titles of the top two posts are:
+            1. "sunt aut facere repellat provident occaecati excepturi optio reprehenderit"
+            2. "qui est esse"
+    """  # noqa: E501
 
     requests_wrapper: TextRequestsWrapper
     """The requests wrapper."""