Update some Tools Docs (#3913)

Haven't gotten to all of them, but this:
- Updates some of the tools notebooks to actually instantiate a tool
(many just show a 'utility' rather than a tool. More changes to come in
separate PR)
- Move the `Tool` and decorator definitions to `langchain/tools/base.py`
(but still export from `langchain.agents`)
- Add scene explain to the load_tools() function
- Add unit tests for public apis for the langchain.tools and langchain.agents modules

tests/unit_tests/agents/test_public_api.py

@@ -0,0 +1,38 @@
+from langchain.agents import __all__ as agents_all
+
+_EXPECTED = [
+    "Agent",
+    "AgentExecutor",
+    "AgentOutputParser",
+    "AgentType",
+    "BaseMultiActionAgent",
+    "BaseSingleActionAgent",
+    "ConversationalAgent",
+    "ConversationalChatAgent",
+    "LLMSingleActionAgent",
+    "MRKLChain",
+    "ReActChain",
+    "ReActTextWorldAgent",
+    "SelfAskWithSearchChain",
+    "Tool",
+    "ZeroShotAgent",
+    "create_csv_agent",
+    "create_json_agent",
+    "create_openapi_agent",
+    "create_pandas_dataframe_agent",
+    "create_pbi_agent",
+    "create_pbi_chat_agent",
+    "create_sql_agent",
+    "create_vectorstore_agent",
+    "create_vectorstore_router_agent",
+    "get_all_tool_names",
+    "initialize_agent",
+    "load_agent",
+    "load_tools",
+    "tool",
+]
+
+
+def test_public_api() -> None:
+    """Test for regressions or changes in the agents public API."""
+    assert agents_all == sorted(_EXPECTED)

tests/unit_tests/tools/test_exported.py

@@ -0,0 +1,35 @@
+from typing import List, Type
+
+import langchain.tools
+from langchain.tools import __all__ as tools_all
+from langchain.tools.base import BaseTool, StructuredTool
+
+_EXCLUDE = {
+    BaseTool,
+    StructuredTool,
+}
+
+
+def _get_tool_classes(skip_tools_without_default_names: bool) -> List[Type[BaseTool]]:
+    results = []
+    for tool_class_name in tools_all:
+        # Resolve the str to the class
+        tool_class = getattr(langchain.tools, tool_class_name)
+        if isinstance(tool_class, type) and issubclass(tool_class, BaseTool):
+            if tool_class in _EXCLUDE:
+                continue
+            if (
+                skip_tools_without_default_names
+                and tool_class.__fields__["name"].default is None
+            ):
+                continue
+            results.append(tool_class)
+    return results
+
+
+def test_tool_names_unique() -> None:
+    """Test that the default names for our core tools are unique."""
+    tool_classes = _get_tool_classes(skip_tools_without_default_names=True)
+    names = sorted([tool_cls.__fields__["name"].default for tool_cls in tool_classes])
+    duplicated_names = [name for name in names if names.count(name) > 1]
+    assert not duplicated_names

tests/unit_tests/tools/test_public_api.py

@@ -0,0 +1,51 @@
+"""Test the public API of the tools package."""
+from langchain.tools import __all__ as public_api
+
+_EXPECTED = [
+    "AIPluginTool",
+    "APIOperation",
+    "BaseTool",
+    "BaseTool",
+    "BaseTool",
+    "BingSearchResults",
+    "BingSearchRun",
+    "ClickTool",
+    "CopyFileTool",
+    "CurrentWebPageTool",
+    "DeleteFileTool",
+    "DuckDuckGoSearchResults",
+    "DuckDuckGoSearchRun",
+    "ExtractHyperlinksTool",
+    "ExtractTextTool",
+    "FileSearchTool",
+    "GetElementsTool",
+    "GooglePlacesTool",
+    "GoogleSearchResults",
+    "GoogleSearchRun",
+    "HumanInputRun",
+    "IFTTTWebhook",
+    "ListDirectoryTool",
+    "MoveFileTool",
+    "NavigateBackTool",
+    "NavigateTool",
+    "OpenAPISpec",
+    "ReadFileTool",
+    "SceneXplainTool",
+    "ShellTool",
+    "StructuredTool",
+    "Tool",
+    "VectorStoreQATool",
+    "VectorStoreQAWithSourcesTool",
+    "WikipediaQueryRun",
+    "WolframAlphaQueryRun",
+    "WriteFileTool",
+    "ZapierNLAListActions",
+    "ZapierNLARunAction",
+    "tool",
+]
+
+
+def test_public_api() -> None:
+    """Test for regressions or changes in the public API."""
+    # Check that the public API is as expected
+    assert public_api == sorted(_EXPECTED)