From 4811a77ca0184db8bdcb2673dbabbd3e83556f0f Mon Sep 17 00:00:00 2001 From: Isaac Francisco <78627776+isahers1@users.noreply.github.com> Date: Tue, 13 Aug 2024 16:10:00 -0700 Subject: [PATCH] [docs]: standardize tool docstrings (#25351) --- docs/vercel.json | 8 ++++ .../integration_template/tools.py | 4 +- .../tools/bing_search/tool.py | 40 ++++++++++++++++- .../tools/ddg_search/tool.py | 36 ++++++++++++++- .../langchain_community/tools/riza/command.py | 38 +++++++++++++++- .../tools/sessions.py | 44 ++++++++++++++++--- libs/partners/exa/langchain_exa/tools.py | 38 +++++++++++++++- 7 files changed, 196 insertions(+), 12 deletions(-) diff --git a/docs/vercel.json b/docs/vercel.json index 36fbad5dc9521..0648210037e4d 100644 --- a/docs/vercel.json +++ b/docs/vercel.json @@ -93,6 +93,14 @@ { "source": "/v0.2/docs/integrations/toolkits/:path(.*/?)*", "destination": "/v0.2/docs/integrations/tools/:path*" + }, + { + "source": "/v0.2/docs/integrations/toolkits/spark/", + "destination": "/v0.2/docs/integrations/tools/spark_sql/" + }, + { + "source": "/v0.2/docs/integrations/toolkits/xorbits/", + "destination": "/v0.2/docs/integrations/tools#search" } ] } diff --git a/libs/cli/langchain_cli/integration_template/integration_template/tools.py b/libs/cli/langchain_cli/integration_template/integration_template/tools.py index 903e8d9db9b59..0ada7bcef564b 100644 --- a/libs/cli/langchain_cli/integration_template/integration_template/tools.py +++ b/libs/cli/langchain_cli/integration_template/integration_template/tools.py @@ -57,12 +57,12 @@ class __ModuleName__Tool(BaseTool): .. code-block:: python # TODO: invoke args - tool.invoke({"args": {...}, "id": "1", "name": tool.name, "type": "tool_call}) + tool.invoke({"args": {...}, "id": "1", "name": tool.name, "type": "tool_call"}) .. code-block:: python # TODO: output of invocation - """ + """ # noqa: E501 # TODO: Set tool name and description name: str = "TODO: Tool name" diff --git a/libs/community/langchain_community/tools/bing_search/tool.py b/libs/community/langchain_community/tools/bing_search/tool.py index 658b5011ca561..63bac6191fb96 100644 --- a/libs/community/langchain_community/tools/bing_search/tool.py +++ b/libs/community/langchain_community/tools/bing_search/tool.py @@ -29,7 +29,45 @@ def _run( class BingSearchResults(BaseTool): - """Tool that queries the Bing Search API and gets back json.""" + """Bing Search tool. + + Setup: + Install ``langchain-community`` and set environment variable ``BING_SUBSCRIPTION_KEY``. + + .. code-block:: bash + + pip install -U langchain-community + export BING_SUBSCRIPTION_KEY="your-api-key" + + Instantiation: + .. code-block:: python + + from langchain_community.tools.bing_search import BingSearchResults + from langchain_community.utilities import BingSearchAPIWrapper + + api_wrapper = BingSearchAPIWrapper() + tool = BingSearchResults(api_wrapper=api_wrapper) + + Invocation with args: + .. code-block:: python + + tool.invoke("what is the weather in SF?") + + .. code-block:: python + + "[{'snippet': 'San Francisco, CA Weather Forecast, with current conditions, wind, air quality, and what to expect for the next 3 days.', 'title': 'San Francisco, CA Weather Forecast | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/weather-forecast/347629'}, {'snippet': 'Tropical Storm Ernesto Forms; Fire Weather Concerns in the Great Basin: Hot Temperatures Return to the South-Central U.S. ... San Francisco CA 37.77°N 122.41°W (Elev. 131 ft) Last Update: 2:21 pm PDT Aug 12, 2024. Forecast Valid: 6pm PDT Aug 12, 2024-6pm PDT Aug 19, 2024 .', 'title': 'National Weather Service', 'link': 'https://forecast.weather.gov/zipcity.php?inputstring=San+Francisco,CA'}, {'snippet': 'Current weather in San Francisco, CA. Check current conditions in San Francisco, CA with radar, hourly, and more.', 'title': 'San Francisco, CA Current Weather | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/current-weather/347629'}, {'snippet': 'Everything you need to know about today's weather in San Francisco, CA. High/Low, Precipitation Chances, Sunrise/Sunset, and today's Temperature History.', 'title': 'Weather Today for San Francisco, CA | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/weather-today/347629'}]" + + Invocation with ToolCall: + + .. code-block:: python + + tool.invoke({"args": {"query":"what is the weather in SF?"}, "id": "1", "name": tool.name, "type": "tool_call"}) + + .. code-block:: python + + ToolMessage(content="[{'snippet': 'Get the latest weather forecast for San Francisco, CA, including temperature, RealFeel, and chance of precipitation. Find out how the weather will affect your plans and activities in the city of ...', 'title': 'San Francisco, CA Weather Forecast | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/weather-forecast/347629'}, {'snippet': 'Radar. Be prepared with the most accurate 10-day forecast for San Francisco, CA with highs, lows, chance of precipitation from The Weather Channel and Weather.com.', 'title': '10-Day Weather Forecast for San Francisco, CA - The Weather Channel', 'link': 'https://weather.com/weather/tenday/l/San+Francisco+CA+USCA0987:1:US'}, {'snippet': 'Tropical Storm Ernesto Forms; Fire Weather Concerns in the Great Basin: Hot Temperatures Return to the South-Central U.S. ... San Francisco CA 37.77°N 122.41°W (Elev. 131 ft) Last Update: 2:21 pm PDT Aug 12, 2024. Forecast Valid: 6pm PDT Aug 12, 2024-6pm PDT Aug 19, 2024 .', 'title': 'National Weather Service', 'link': 'https://forecast.weather.gov/zipcity.php?inputstring=San+Francisco,CA'}, {'snippet': 'Current weather in San Francisco, CA. Check current conditions in San Francisco, CA with radar, hourly, and more.', 'title': 'San Francisco, CA Current Weather | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/current-weather/347629'}]", name='bing_search_results_json', tool_call_id='1') + + """ # noqa: E501 name: str = "bing_search_results_json" description: str = ( diff --git a/libs/community/langchain_community/tools/ddg_search/tool.py b/libs/community/langchain_community/tools/ddg_search/tool.py index fa1c01bedde2c..3be46f5b94406 100644 --- a/libs/community/langchain_community/tools/ddg_search/tool.py +++ b/libs/community/langchain_community/tools/ddg_search/tool.py @@ -17,7 +17,41 @@ class DDGInput(BaseModel): class DuckDuckGoSearchRun(BaseTool): - """Tool that queries the DuckDuckGo search API.""" + """DuckDuckGo tool. + + Setup: + Install ``duckduckgo-search`` and ``langchain-community``. + + .. code-block:: bash + + pip install -U duckduckgo-search langchain-community + + Instantiation: + .. code-block:: python + + from langchain_community.tools import DuckDuckGoSearchResults + + tool = DuckDuckGoSearchResults() + + Invocation with args: + .. code-block:: python + + tool.invoke("Obama") + + .. code-block:: python + + '[snippet: Users on X have been widely comparing the boost of support felt for Kamala Harris\' campaign to Barack Obama\'s in 2008., title: Surging Support For Kamala Harris Compared To Obama-Era Energy, link: https://www.msn.com/en-us/news/politics/surging-support-for-kamala-harris-compared-to-obama-era-energy/ar-BB1qzdC0, date: 2024-07-24T18:27:01+00:00, source: Newsweek on MSN.com], [snippet: Harris tried to emulate Obama\'s coalition in 2020 and failed. She may have a better shot at reaching young, Black, and Latino voters this time around., title: Harris May Follow Obama\'s Path to the White House After All, link: https://www.msn.com/en-us/news/politics/harris-may-follow-obama-s-path-to-the-white-house-after-all/ar-BB1qv9d4, date: 2024-07-23T22:42:00+00:00, source: Intelligencer on MSN.com], [snippet: The Republican presidential candidate said in an interview on Fox News that he "wouldn\'t be worried" about Michelle Obama running., title: Donald Trump Responds to Michelle Obama Threat, link: https://www.msn.com/en-us/news/politics/donald-trump-responds-to-michelle-obama-threat/ar-BB1qqtu5, date: 2024-07-22T18:26:00+00:00, source: Newsweek on MSN.com], [snippet: H eading into the weekend at his vacation home in Rehoboth Beach, Del., President Biden was reportedly stewing over Barack Obama\'s role in the orchestrated campaign to force him, title: Opinion | Barack Obama Strikes Again, link: https://www.msn.com/en-us/news/politics/opinion-barack-obama-strikes-again/ar-BB1qrfiy, date: 2024-07-22T21:28:00+00:00, source: The Wall Street Journal on MSN.com]' + + Invocation with ToolCall: + + .. code-block:: python + + tool.invoke({"args": {"query":"Obama"}, "id": "1", "name": tool.name, "type": "tool_call"}) + + .. code-block:: python + + ToolMessage(content="[snippet: Biden, Obama and the Clintons Will Speak at the Democratic Convention. The president, two of his predecessors and the party's 2016 nominee are said to be planning speeches at the party's ..., title: Biden, Obama and the Clintons Will Speak at the Democratic Convention ..., link: https://www.nytimes.com/2024/08/12/us/politics/dnc-speakers-biden-obama-clinton.html], [snippet: Barack Obama—with his wife, Michelle—being sworn in as the 44th president of the United States, January 20, 2009. Key events in the life of Barack Obama. Barack Obama (born August 4, 1961, Honolulu, Hawaii, U.S.) is the 44th president of the United States (2009-17) and the first African American to hold the office., title: Barack Obama | Biography, Parents, Education, Presidency, Books ..., link: https://www.britannica.com/biography/Barack-Obama], [snippet: Former President Barack Obama released a letter about President Biden's decision to drop out of the 2024 presidential race. Notably, Obama did not name or endorse Vice President Kamala Harris., title: Read Obama's full statement on Biden dropping out - CBS News, link: https://www.cbsnews.com/news/barack-obama-biden-dropping-out-2024-presidential-race-full-statement/], [snippet: Many of the marquee names in Democratic politics began quickly lining up behind Vice President Kamala Harris on Sunday, but one towering presence in the party held back: Barack Obama. The former ..., title: Why Obama Hasn't Endorsed Harris - The New York Times, link: https://www.nytimes.com/2024/07/21/us/politics/why-obama-hasnt-endorsed-harris.html]", name='duckduckgo_results_json', tool_call_id='1') + """ # noqa: E501 name: str = "duckduckgo_search" description: str = ( diff --git a/libs/community/langchain_community/tools/riza/command.py b/libs/community/langchain_community/tools/riza/command.py index ce9451121f086..cfc36865768af 100644 --- a/libs/community/langchain_community/tools/riza/command.py +++ b/libs/community/langchain_community/tools/riza/command.py @@ -19,7 +19,43 @@ class ExecPythonInput(BaseModel): class ExecPython(BaseTool): - """A tool implementation to execute Python via Riza's Code Interpreter API.""" + """Riza Code tool. + + Setup: + Install ``langchain-community`` and ``rizaio`` and set environment variable ``RIZA_API_KEY``. + + .. code-block:: bash + + pip install -U langchain-community rizaio + export RIZA_API_KEY="your-api-key" + + Instantiation: + .. code-block:: python + + from langchain_community.tools.riza.command import ExecPython + + tool = ExecPython() + + Invocation with args: + .. code-block:: python + + tool.invoke("x = 5; print(x)") + + .. code-block:: python + + '5\\n' + + Invocation with ToolCall: + + .. code-block:: python + + tool.invoke({"args": {"code":"x = 5; print(x)"}, "id": "1", "name": tool.name, "type": "tool_call"}) + + .. code-block:: python + + tool.invoke({"args": {"code":"x = 5; print(x)"}, "id": "1", "name": tool.name, "type": "tool_call"}) + + """ # noqa: E501 name: str = "riza_exec_python" description: str = """Execute Python code to solve problems. diff --git a/libs/partners/azure-dynamic-sessions/langchain_azure_dynamic_sessions/tools/sessions.py b/libs/partners/azure-dynamic-sessions/langchain_azure_dynamic_sessions/tools/sessions.py index 99d5b3b034091..f71464488cfea 100644 --- a/libs/partners/azure-dynamic-sessions/langchain_azure_dynamic_sessions/tools/sessions.py +++ b/libs/partners/azure-dynamic-sessions/langchain_azure_dynamic_sessions/tools/sessions.py @@ -92,18 +92,50 @@ def from_dict(data: dict) -> "RemoteFileMetadata": class SessionsPythonREPLTool(BaseTool): - """A tool for running Python code. + r"""Azure Dynamic Sessions tool. - Run python code in an Azure Container Apps dynamic sessions code interpreter. + Setup: + Install ``langchain-azure-dynamic-sessions`` and create a session pool, which you can do by following the instructions [here](https://learn.microsoft.com/en-us/azure/container-apps/sessions-code-interpreter?tabs=azure-cli#create-a-session-pool-with-azure-cli). - Example: + .. code-block:: bash + + pip install -U langchain-azure-dynamic-sessions + + .. code-block:: python + + import getpass + + POOL_MANAGEMENT_ENDPOINT = getpass.getpass("Enter the management endpoint of the session pool: ") + + Instantiation: .. code-block:: python from langchain_azure_dynamic_sessions import SessionsPythonREPLTool - tool = SessionsPythonREPLTool(pool_management_endpoint="...") - result = tool.invoke("6 * 7") - """ + tool = SessionsPythonREPLTool( + pool_management_endpoint=POOL_MANAGEMENT_ENDPOINT + ) + + + Invocation with args: + .. code-block:: python + + tool.invoke("6 * 7") + + .. code-block:: python + + '{\\n "result": 42,\\n "stdout": "",\\n "stderr": ""\\n}' + + Invocation with ToolCall: + + .. code-block:: python + + tool.invoke({"args": {"input":"6 * 7"}, "id": "1", "name": tool.name, "type": "tool_call"}) + + .. code-block:: python + + '{\\n "result": 42,\\n "stdout": "",\\n "stderr": ""\\n}' + """ # noqa: E501 name: str = "Python_REPL" description: str = ( diff --git a/libs/partners/exa/langchain_exa/tools.py b/libs/partners/exa/langchain_exa/tools.py index a6d98ec9b72f9..808f6bdc57c67 100644 --- a/libs/partners/exa/langchain_exa/tools.py +++ b/libs/partners/exa/langchain_exa/tools.py @@ -14,7 +14,43 @@ class ExaSearchResults(BaseTool): - """Tool that queries the Metaphor Search API and gets back json.""" + """Exa Search tool. + + Setup: + Install ``langchain-exa`` and set environment variable ``EXA_API_KEY``. + + .. code-block:: bash + + pip install -U langchain-exa + export EXA_API_KEY="your-api-key" + + Instantiation: + .. code-block:: python + + from langchain-exa import ExaSearchResults + + tool = ExaSearchResults() + + Invocation with args: + .. code-block:: python + + tool.invoke({"query":"what is the weather in SF","num_results":1}) + + .. code-block:: python + + SearchResponse(results=[Result(url='https://www.wunderground.com/weather/37.8,-122.4', id='https://www.wunderground.com/weather/37.8,-122.4', title='San Francisco, CA Weather Conditionsstar_ratehome', score=0.1843988299369812, published_date='2023-02-23T01:17:06.594Z', author=None, text='The time period when the sun is no more than 6 degrees below the horizon at either sunrise or sunset. The horizon should be clearly defined and the brightest stars should be visible under good atmospheric conditions (i.e. no moonlight, or other lights). One still should be able to carry on ordinary outdoor activities. The time period when the sun is between 6 and 12 degrees below the horizon at either sunrise or sunset. The horizon is well defined and the outline of objects might be visible without artificial light. Ordinary outdoor activities are not possible at this time without extra illumination. The time period when the sun is between 12 and 18 degrees below the horizon at either sunrise or sunset. The sun does not contribute to the illumination of the sky before this time in the morning, or after this time in the evening. In the beginning of morning astronomical twilight and at the end of astronomical twilight in the evening, sky illumination is very faint, and might be undetectable. The time of Civil Sunset minus the time of Civil Sunrise. The time of Actual Sunset minus the time of Actual Sunrise. The change in length of daylight between today and tomorrow is also listed when available.', highlights=None, highlight_scores=None, summary=None)], autoprompt_string=None) + + Invocation with ToolCall: + + .. code-block:: python + + tool.invoke({"args": {"query":"what is the weather in SF","num_results":1}, "id": "1", "name": tool.name, "type": "tool_call"}) + + .. code-block:: python + + ToolMessage(content='Title: San Francisco, CA Weather Conditionsstar_ratehome\nURL: https://www.wunderground.com/weather/37.8,-122.4\nID: https://www.wunderground.com/weather/37.8,-122.4\nScore: 0.1843988299369812\nPublished Date: 2023-02-23T01:17:06.594Z\nAuthor: None\nText: The time period when the sun is no more than 6 degrees below the horizon at either sunrise or sunset. The horizon should be clearly defined and the brightest stars should be visible under good atmospheric conditions (i.e. no moonlight, or other lights). One still should be able to carry on ordinary outdoor activities. The time period when the sun is between 6 and 12 degrees below the horizon at either sunrise or sunset. The horizon is well defined and the outline of objects might be visible without artificial light. Ordinary outdoor activities are not possible at this time without extra illumination. The time period when the sun is between 12 and 18 degrees below the horizon at either sunrise or sunset. The sun does not contribute to the illumination of the sky before this time in the morning, or after this time in the evening. In the beginning of morning astronomical twilight and at the end of astronomical twilight in the evening, sky illumination is very faint, and might be undetectable. The time of Civil Sunset minus the time of Civil Sunrise. The time of Actual Sunset minus the time of Actual Sunrise. The change in length of daylight between today and tomorrow is also listed when available.\nHighlights: None\nHighlight Scores: None\nSummary: None\n', name='exa_search_results_json', tool_call_id='1') + + """ # noqa: E501 name: str = "exa_search_results_json" description: str = (