diff --git a/libs/langchain/langchain/agents/__init__.py b/libs/langchain/langchain/agents/__init__.py index ae0636997b1..76754c70757 100644 --- a/libs/langchain/langchain/agents/__init__.py +++ b/libs/langchain/langchain/agents/__init__.py @@ -1,4 +1,33 @@ -"""Interface for agents.""" +""" +**Agent** is a class that uses an LLM to choose a sequence of actions to take. + +In Chains, a sequence of actions is hardcoded. In Agents, +a language model is used as a reasoning engine to determine which actions +to take and in which order. + +Agents select and use **Tools** and **Toolkits** for actions. + +**Class hierarchy:** + +.. code-block:: + + BaseSingleActionAgent --> LLMSingleActionAgent + OpenAIFunctionsAgent + XMLAgent + Agent --> Agent # Examples: ZeroShotAgent, ChatAgent + + + BaseMultiActionAgent --> OpenAIMultiFunctionsAgent + + +**Main helpers:** + +.. code-block:: + + AgentType, AgentExecutor, AgentOutputParser, AgentExecutorIterator, + AgentAction, AgentFinish + +""" # noqa: E501 from langchain.agents.agent import ( Agent, AgentExecutor, diff --git a/libs/langchain/langchain/cache.py b/libs/langchain/langchain/cache.py index 0422d13ddc4..2136acaad18 100644 --- a/libs/langchain/langchain/cache.py +++ b/libs/langchain/langchain/cache.py @@ -1,4 +1,24 @@ -"""Beta Feature: base interface for cache.""" +""" +.. warning:: + Beta Feature! + +**Cache** provides an optional caching layer for LLMs. + +Cache is useful for two reasons: + +- It can save you money by reducing the number of API calls you make to the LLM + provider if you're often requesting the same completion multiple times. +- It can speed up your application by reducing the number of API calls you make + to the LLM provider. + +Cache directly competes with Memory. See documentation for Pros and Cons. + +**Class hierarchy:** + +.. code-block:: + + BaseCache --> Cache # Examples: InMemoryCache, RedisCache, GPTCache +""" from __future__ import annotations import hashlib diff --git a/libs/langchain/langchain/callbacks/__init__.py b/libs/langchain/langchain/callbacks/__init__.py index 0d9335b23e3..ca70b0bd389 100644 --- a/libs/langchain/langchain/callbacks/__init__.py +++ b/libs/langchain/langchain/callbacks/__init__.py @@ -1,4 +1,11 @@ -"""Callback handlers that allow listening to events in LangChain.""" +"""**Callback handlers** allow listening to events in LangChain. + +**Class hierarchy:** + +.. code-block:: + + BaseCallbackHandler --> CallbackHandler # Example: AimCallbackHandler +""" from langchain.callbacks.aim_callback import AimCallbackHandler from langchain.callbacks.argilla_callback import ArgillaCallbackHandler diff --git a/libs/langchain/langchain/chains/__init__.py b/libs/langchain/langchain/chains/__init__.py index 6dbfcbd3439..8564d6851a3 100644 --- a/libs/langchain/langchain/chains/__init__.py +++ b/libs/langchain/langchain/chains/__init__.py @@ -1,16 +1,21 @@ -"""Chains are easily reusable components which can be linked together. +"""**Chains** are easily reusable components linked together. - Chains should be used to encode a sequence of calls to components like - models, document retrievers, other chains, etc., and provide a simple interface - to this sequence. +Chains encode a sequence of calls to components like models, document retrievers, +other Chains, etc., and provide a simple interface to this sequence. - The Chain interface makes it easy to create apps that are: - - Stateful: add Memory to any Chain to give it state, - - Observable: pass Callbacks to a Chain to execute additional functionality, - like logging, outside the main sequence of component calls, - - Composable: the Chain API is flexible enough that it is easy to combine - Chains with other components, including other Chains. - """ +The Chain interface makes it easy to create apps that are: + + - **Stateful:** add Memory to any Chain to give it state, + - **Observable:** pass Callbacks to a Chain to execute additional functionality, + like logging, outside the main sequence of component calls, + - **Composable:** combine Chains with other components, including other Chains. + +**Class hierarchy:** + +.. code-block:: + + Chain --> Chain # Examples: LLMChain, MapReduceChain, RouterChain +""" from langchain.chains.api.base import APIChain from langchain.chains.api.openapi.chain import OpenAPIEndpointChain diff --git a/libs/langchain/langchain/chat_models/__init__.py b/libs/langchain/langchain/chat_models/__init__.py index 0f7ead9d3cc..a05fd32958a 100644 --- a/libs/langchain/langchain/chat_models/__init__.py +++ b/libs/langchain/langchain/chat_models/__init__.py @@ -1,3 +1,22 @@ +"""**Chat Models** are a variation on language models. + +While Chat Models use language models under the hood, the interface they expose +is a bit different. Rather than expose a "text in, text out" API, they expose +an interface where "chat messages" are the inputs and outputs. + +**Class hierarchy:** + +.. code-block:: + + BaseLanguageModel --> BaseChatModel --> # Examples: ChatOpenAI, ChatGooglePalm + +**Main helpers:** + +.. code-block:: + + AIMessage, BaseMessage, HumanMessage +""" # noqa: E501 + from langchain.chat_models.anthropic import ChatAnthropic from langchain.chat_models.azure_openai import AzureChatOpenAI from langchain.chat_models.fake import FakeListChatModel diff --git a/libs/langchain/langchain/docstore/__init__.py b/libs/langchain/langchain/docstore/__init__.py index b5c3c565418..7814d7f30cf 100644 --- a/libs/langchain/langchain/docstore/__init__.py +++ b/libs/langchain/langchain/docstore/__init__.py @@ -1,4 +1,19 @@ -"""Wrappers on top of docstores.""" +"""**Docstores** are classes to store and load Documents. + +The **Docstore** is a simplified version of the Document Loader. + +**Class hierarchy:** + +.. code-block:: + + Docstore --> # Examples: InMemoryDocstore, Wikipedia + +**Main helpers:** + +.. code-block:: + + Document, AddableMixin +""" from langchain.docstore.arbitrary_fn import DocstoreFn from langchain.docstore.in_memory import InMemoryDocstore from langchain.docstore.wikipedia import Wikipedia diff --git a/libs/langchain/langchain/document_loaders/__init__.py b/libs/langchain/langchain/document_loaders/__init__.py index 5d985ae2803..34446a33a48 100644 --- a/libs/langchain/langchain/document_loaders/__init__.py +++ b/libs/langchain/langchain/document_loaders/__init__.py @@ -1,4 +1,19 @@ -"""All different types of document loaders.""" +"""**Document Loaders** are classes to load Documents. + +**Document Loaders** are usually used to load a lot of Documents in a single run. + +**Class hierarchy:** + +.. code-block:: + + BaseLoader --> Loader # Examples: TextLoader, UnstructuredFileLoader + +**Main helpers:** + +.. code-block:: + + Document, TextSplitter +""" from langchain.document_loaders.acreom import AcreomLoader from langchain.document_loaders.airbyte_json import AirbyteJSONLoader diff --git a/libs/langchain/langchain/document_transformers/__init__.py b/libs/langchain/langchain/document_transformers/__init__.py index 43678d2e753..69b3b89ae2d 100644 --- a/libs/langchain/langchain/document_transformers/__init__.py +++ b/libs/langchain/langchain/document_transformers/__init__.py @@ -1,3 +1,20 @@ +"""**Document Transformers** are classes to transform Documents. + +**Document Transformers** usually used to transform a lot of Documents in a single run. + +**Class hierarchy:** + +.. code-block:: + + BaseDocumentTransformer --> # Examples: DoctranQATransformer, DoctranTextTranslator + +**Main helpers:** + +.. code-block:: + + Document +""" # noqa: E501 + from langchain.document_transformers.doctran_text_extract import ( DoctranPropertyExtractor, ) @@ -10,6 +27,7 @@ from langchain.document_transformers.embeddings_redundant_filter import ( ) from langchain.document_transformers.html2text import Html2TextTransformer from langchain.document_transformers.long_context_reorder import LongContextReorder +from langchain.document_transformers.openai_functions import OpenAIMetadataTagger __all__ = [ "DoctranQATransformer", @@ -22,5 +40,3 @@ __all__ = [ "OpenAIMetadataTagger", "Html2TextTransformer", ] - -from langchain.document_transformers.openai_functions import OpenAIMetadataTagger diff --git a/libs/langchain/langchain/embeddings/__init__.py b/libs/langchain/langchain/embeddings/__init__.py index 4ad8943e73e..0afb9a06e9e 100644 --- a/libs/langchain/langchain/embeddings/__init__.py +++ b/libs/langchain/langchain/embeddings/__init__.py @@ -1,4 +1,16 @@ -"""Wrappers around embedding modules.""" +"""**Embedding models** are wrappers around embedding models +from different APIs and services. + +**Embedding models** can be LLMs or not. + +**Class hierarchy:** + +.. code-block:: + + Embeddings --> Embeddings # Examples: OpenAIEmbeddings, HuggingFaceEmbeddings +""" + + import logging from typing import Any diff --git a/libs/langchain/langchain/env.py b/libs/langchain/langchain/env.py index b76dab95e20..46c571ca265 100644 --- a/libs/langchain/langchain/env.py +++ b/libs/langchain/langchain/env.py @@ -4,7 +4,7 @@ from functools import lru_cache @lru_cache(maxsize=1) def get_runtime_environment() -> dict: - """Get information about the environment.""" + """Get information about the LangChain runtime environment.""" # Lazy import to avoid circular imports from langchain import __version__ diff --git a/libs/langchain/langchain/evaluation/__init__.py b/libs/langchain/langchain/evaluation/__init__.py index b59fec88ce3..b3d919f0226 100644 --- a/libs/langchain/langchain/evaluation/__init__.py +++ b/libs/langchain/langchain/evaluation/__init__.py @@ -1,4 +1,4 @@ -"""Evaluation chains for grading LLM and Chain outputs. +"""**Evaluation** chains for grading LLM and Chain outputs. This module contains off-the-shelf evaluation chains for grading the output of LangChain primitives such as language models and chains. diff --git a/libs/langchain/langchain/graphs/__init__.py b/libs/langchain/langchain/graphs/__init__.py index a0786a4fa73..e0b2d639eac 100644 --- a/libs/langchain/langchain/graphs/__init__.py +++ b/libs/langchain/langchain/graphs/__init__.py @@ -1,4 +1,5 @@ -"""Graph implementations.""" +"""**Graphs** provide a natural language interface to graph databases.""" + from langchain.graphs.arangodb_graph import ArangoGraph from langchain.graphs.hugegraph import HugeGraph from langchain.graphs.kuzu_graph import KuzuGraph diff --git a/libs/langchain/langchain/indexes/__init__.py b/libs/langchain/langchain/indexes/__init__.py index 7e81e4ac88c..d0c878915d8 100644 --- a/libs/langchain/langchain/indexes/__init__.py +++ b/libs/langchain/langchain/indexes/__init__.py @@ -1,4 +1,4 @@ -"""All index utils.""" +"""**Index** utilities.""" from langchain.indexes.graph import GraphIndexCreator from langchain.indexes.vectorstore import VectorstoreIndexCreator diff --git a/libs/langchain/langchain/llms/__init__.py b/libs/langchain/langchain/llms/__init__.py index 766d3af4e15..57de544a484 100644 --- a/libs/langchain/langchain/llms/__init__.py +++ b/libs/langchain/langchain/llms/__init__.py @@ -1,4 +1,22 @@ -"""Access to the large language model APIs and services.""" +""" +**LLM** classes provide +access to the large language model (**LLM**) APIs and services. + +**Class hierarchy:** + +.. code-block:: + + BaseLanguageModel --> BaseLLM --> LLM --> # Examples: AI21, HuggingFaceHub, OpenAI + +**Main helpers:** + +.. code-block:: + + LLMResult, PromptValue, + CallbackManagerForLLMRun, AsyncCallbackManagerForLLMRun, + CallbackManager, AsyncCallbackManager, + AIMessage, BaseMessage +""" # noqa: E501 from typing import Dict, Type from langchain.llms.ai21 import AI21 diff --git a/libs/langchain/langchain/load/__init__.py b/libs/langchain/langchain/load/__init__.py index e69de29bb2d..e1c042ba376 100644 --- a/libs/langchain/langchain/load/__init__.py +++ b/libs/langchain/langchain/load/__init__.py @@ -0,0 +1 @@ +"""Serialization and deserialization.""" diff --git a/libs/langchain/langchain/memory/__init__.py b/libs/langchain/langchain/memory/__init__.py index de669b47784..76fc7c92ed5 100644 --- a/libs/langchain/langchain/memory/__init__.py +++ b/libs/langchain/langchain/memory/__init__.py @@ -1,4 +1,31 @@ -"""Memory maintains Chain state, incorporating context from past runs.""" +"""**Memory** maintains Chain state, incorporating context from past runs. + +**Class hierarchy for Memory:** + +.. code-block:: + + BaseMemory --> BaseChatMemory --> Memory # Examples: ZepMemory, MotorheadMemory + +**Main helpers:** + +.. code-block:: + + BaseChatMessageHistory + +**Chat Message History** stores the chat message history in different stores. + +**Class hierarchy for ChatMessageHistory:** + +.. code-block:: + + BaseChatMessageHistory --> ChatMessageHistory # Example: ZepChatMessageHistory + +**Main helpers:** + +.. code-block:: + + AIMessage, BaseMessage, HumanMessage +""" # noqa: E501 from langchain.memory.buffer import ( ConversationBufferMemory, ConversationStringBufferMemory, diff --git a/libs/langchain/langchain/output_parsers/__init__.py b/libs/langchain/langchain/output_parsers/__init__.py index 1aa064a9c59..f029f52bfb8 100644 --- a/libs/langchain/langchain/output_parsers/__init__.py +++ b/libs/langchain/langchain/output_parsers/__init__.py @@ -1,3 +1,17 @@ +"""**OutputParser** classes parse the output of an LLM call. + +**Class hierarchy:** + +.. code-block:: + + BaseLLMOutputParser --> BaseOutputParser --> OutputParser # ListOutputParser, PydanticOutputParser + +**Main helpers:** + +.. code-block:: + + Serializable, Generation, PromptValue +""" # noqa: E501 from langchain.output_parsers.boolean import BooleanOutputParser from langchain.output_parsers.combining import CombiningOutputParser from langchain.output_parsers.datetime import DatetimeOutputParser diff --git a/libs/langchain/langchain/prompts/__init__.py b/libs/langchain/langchain/prompts/__init__.py index d91f1d9a374..66c2dbe1223 100644 --- a/libs/langchain/langchain/prompts/__init__.py +++ b/libs/langchain/langchain/prompts/__init__.py @@ -1,4 +1,32 @@ -"""Prompt template classes.""" +"""**Prompt** is the input to the model. + +Prompt is often constructed +from multiple components. Prompt classes and functions make constructing + and working with prompts easy. + +**Class hierarchy:** + +.. code-block:: + + BasePromptTemplate --> PipelinePromptTemplate + StringPromptTemplate --> PromptTemplate + FewShotPromptTemplate + FewShotPromptWithTemplates + BaseChatPromptTemplate --> AutoGPTPrompt + ChatPromptTemplate --> AgentScratchPadChatPromptTemplate + + + + BaseMessagePromptTemplate --> MessagesPlaceholder + BaseStringMessagePromptTemplate --> ChatMessagePromptTemplate + HumanMessagePromptTemplate + AIMessagePromptTemplate + SystemMessagePromptTemplate + + PromptValue --> StringPromptValue + ChatPromptValue + +""" # noqa: E501 from langchain.prompts.base import StringPromptTemplate from langchain.prompts.chat import ( AIMessagePromptTemplate, diff --git a/libs/langchain/langchain/retrievers/__init__.py b/libs/langchain/langchain/retrievers/__init__.py index 72a3b28f31d..c820daa9825 100644 --- a/libs/langchain/langchain/retrievers/__init__.py +++ b/libs/langchain/langchain/retrievers/__init__.py @@ -1,3 +1,23 @@ +"""**Retriever** class returns Documents given a text **query**. + +It is more general than a vector store. A retriever does not need to be able to +store documents, only to return (or retrieve) it. Vector stores can be used as +the backbone of a retriever, but there are other types of retrievers as well. + +**Class hierarchy:** + +.. code-block:: + + BaseRetriever --> Retriever # Examples: ArxivRetriever, MergerRetriever + +**Main helpers:** + +.. code-block:: + + Document, Serializable, Callbacks, + CallbackManagerForRetrieverRun, AsyncCallbackManagerForRetrieverRun +""" + from langchain.retrievers.arxiv import ArxivRetriever from langchain.retrievers.azure_cognitive_search import AzureCognitiveSearchRetriever from langchain.retrievers.bm25 import BM25Retriever diff --git a/libs/langchain/langchain/schema/__init__.py b/libs/langchain/langchain/schema/__init__.py index e4235c85f7a..bba898f0bc9 100644 --- a/libs/langchain/langchain/schema/__init__.py +++ b/libs/langchain/langchain/schema/__init__.py @@ -1,3 +1,4 @@ +"""**Schemas** are the LangChain Base Classes and Interfaces.""" from langchain.schema.agent import AgentAction, AgentFinish from langchain.schema.document import BaseDocumentTransformer, Document from langchain.schema.memory import BaseChatMessageHistory, BaseMemory diff --git a/libs/langchain/langchain/smith/__init__.py b/libs/langchain/langchain/smith/__init__.py index 16e882f127e..9786c9eef3e 100644 --- a/libs/langchain/langchain/smith/__init__.py +++ b/libs/langchain/langchain/smith/__init__.py @@ -1,4 +1,4 @@ -"""LangSmith utilities. +"""**LangSmith** utilities. This module provides utilities for connecting to `LangSmith `_. For more information on LangSmith, see the `LangSmith documentation `_. diff --git a/libs/langchain/langchain/text_splitter.py b/libs/langchain/langchain/text_splitter.py index 0b590640099..be57522f0f7 100644 --- a/libs/langchain/langchain/text_splitter.py +++ b/libs/langchain/langchain/text_splitter.py @@ -1,4 +1,24 @@ -"""Functionality for splitting text.""" +"""**Text Splitters** are classes for splitting text. + + +**Class hierarchy:** + +.. code-block:: + + BaseDocumentTransformer --> TextSplitter --> TextSplitter # Example: CharacterTextSplitter + RecursiveCharacterTextSplitter --> TextSplitter + +Note: **MarkdownHeaderTextSplitter** does not derive from TextSplitter. + + +**Main helpers:** + +.. code-block:: + + Document, Tokenizer, Language, LineType, HeaderType + +""" # noqa: E501 + from __future__ import annotations import copy diff --git a/libs/langchain/langchain/tools/__init__.py b/libs/langchain/langchain/tools/__init__.py index 3b58d99f02a..ad4ae9635a8 100644 --- a/libs/langchain/langchain/tools/__init__.py +++ b/libs/langchain/langchain/tools/__init__.py @@ -1,4 +1,21 @@ -"""Core toolkit implementations.""" +"""**Tools** are classes that an Agent uses to interact with the world. + +Each tool has a **description**. Agent uses the description to choose the right +tool for the job. + +**Class hierarchy:** + +.. code-block:: + + ToolMetaclass --> BaseTool --> Tool # Examples: AIPluginTool, BaseGraphQLTool + # Examples: BraveSearch, HumanInputRun + +**Main helpers:** + +.. code-block:: + + CallbackManagerForToolRun, AsyncCallbackManagerForToolRun +""" from langchain.tools.arxiv.tool import ArxivQueryRun from langchain.tools.azure_cognitive_services import ( @@ -113,8 +130,6 @@ __all__ = [ "BaseSQLDatabaseTool", "BaseSparkSQLTool", "BaseTool", - "BaseTool", - "BaseTool", "BingSearchResults", "BingSearchRun", "BraveSearch", diff --git a/libs/langchain/langchain/utilities/__init__.py b/libs/langchain/langchain/utilities/__init__.py index e05148a1e8c..0482ccafd25 100644 --- a/libs/langchain/langchain/utilities/__init__.py +++ b/libs/langchain/langchain/utilities/__init__.py @@ -1,4 +1,8 @@ -"""Generic integrations with third-part systems and packages.""" +"""**Utilities** are the integrations with third-part systems and packages. + +Other LangChain classes use **Utilities** to interact with third-part systems +and packages. +""" from langchain.utilities.arxiv import ArxivAPIWrapper from langchain.utilities.awslambda import LambdaWrapper from langchain.utilities.bash import BashProcess diff --git a/libs/langchain/langchain/utils/__init__.py b/libs/langchain/langchain/utils/__init__.py index 1242144c7a6..61be7e8706f 100644 --- a/libs/langchain/langchain/utils/__init__.py +++ b/libs/langchain/langchain/utils/__init__.py @@ -1,7 +1,7 @@ """ -Utility functions for langchain. +**Utility functions** for LangChain. -These functions do not depend on any other langchain modules. +These functions do not depend on any other LangChain module. """ from langchain.utils.env import get_from_dict_or_env, get_from_env diff --git a/libs/langchain/langchain/vectorstores/__init__.py b/libs/langchain/langchain/vectorstores/__init__.py index c4eeed02edb..31d0bf20f4a 100644 --- a/libs/langchain/langchain/vectorstores/__init__.py +++ b/libs/langchain/langchain/vectorstores/__init__.py @@ -1,4 +1,23 @@ -"""Wrappers on top of vector stores.""" +"""**Vector store** stores embedded data and performs vector search. + +One of the most common ways to store and search over unstructured data is to +embed it and store the resulting embedding vectors, and then query the store +and retrieve the data that are 'most similar' to the embedded query. + +**Class hierarchy:** + +.. code-block:: + + VectorStore --> # Examples: Annoy, FAISS, Milvus + + BaseRetriever --> VectorStoreRetriever --> Retriever # Example: VespaRetriever + +**Main helpers:** + +.. code-block:: + + Embeddings, Document +""" # noqa: E501 from langchain.vectorstores.alibabacloud_opensearch import ( AlibabaCloudOpenSearch, AlibabaCloudOpenSearchSettings, diff --git a/libs/langchain/tests/unit_tests/tools/test_public_api.py b/libs/langchain/tests/unit_tests/tools/test_public_api.py index 2873f188c23..43c2fb905ae 100644 --- a/libs/langchain/tests/unit_tests/tools/test_public_api.py +++ b/libs/langchain/tests/unit_tests/tools/test_public_api.py @@ -14,8 +14,6 @@ _EXPECTED = [ "BaseSQLDatabaseTool", "BaseSparkSQLTool", "BaseTool", - "BaseTool", - "BaseTool", "BingSearchResults", "BingSearchRun", "BraveSearch", @@ -102,4 +100,4 @@ _EXPECTED = [ def test_public_api() -> None: """Test for regressions or changes in the public API.""" # Check that the public API is as expected - assert sorted(public_api) == sorted(_EXPECTED) + assert set(public_api) == set(_EXPECTED)