diff --git a/docs/docs/contributing/how_to/integrations/package.mdx b/docs/docs/contributing/how_to/integrations/package.mdx
index 795bef2e03310..990f097fd2a19 100644
--- a/docs/docs/contributing/how_to/integrations/package.mdx
+++ b/docs/docs/contributing/how_to/integrations/package.mdx
@@ -12,9 +12,178 @@ which contain classes that are compatible with LangChain's core interfaces.
We will cover:
-1. How to implement components, such as [chat models](/docs/concepts/chat_models/) and [vector stores](/docs/concepts/vectorstores/), that adhere
+1. (Optional) How to bootstrap a new integration package
+2. How to implement components, such as [chat models](/docs/concepts/chat_models/) and [vector stores](/docs/concepts/vectorstores/), that adhere
to the LangChain interface;
-2. (Optional) How to bootstrap a new integration package.
+
+## (Optional) bootstrapping a new integration package
+
+In this section, we will outline 2 options for bootstrapping a new integration package,
+and you're welcome to use other tools if you prefer!
+
+1. **langchain-cli**: This is a command-line tool that can be used to bootstrap a new integration package with a template for LangChain components and Poetry for dependency management.
+2. **Poetry**: This is a Python dependency management tool that can be used to bootstrap a new Python package with dependencies. You can then add LangChain components to this package.
+
+
+ Option 1: langchain-cli (recommended)
+
+In this guide, we will be using the `langchain-cli` to create a new integration package
+from a template, which can be edited to implement your LangChain components.
+
+### **Prerequisites**
+
+- [GitHub](https://github.com) account
+- [PyPi](https://pypi.org/) account
+
+### Boostrapping a new Python package with langchain-cli
+
+First, install `langchain-cli` and `poetry`:
+
+```bash
+pip install langchain-cli poetry
+```
+
+Next, come up with a name for your package. For this guide, we'll use `langchain-parrot-link`.
+You can confirm that the name is available on PyPi by searching for it on the [PyPi website](https://pypi.org/).
+
+Next, create your new Python package with `langchain-cli`, and navigate into the new directory with `cd`:
+
+```bash
+langchain-cli integration new
+
+> The name of the integration to create (e.g. `my-integration`): parrot-link
+> Name of integration in PascalCase [ParrotLink]:
+
+cd parrot-link
+```
+
+Next, let's add any dependencies we need
+
+```bash
+poetry add my-integration-sdk
+```
+
+We can also add some `typing` or `test` dependencies in a separate poetry dependency group.
+
+```
+poetry add --group typing my-typing-dep
+poetry add --group test my-test-dep
+```
+
+And finally, have poetry set up a virtual environment with your dependencies, as well
+as your integration package:
+
+```bash
+poetry install --with lint,typing,test,test_integration
+```
+
+You now have a new Python package with a template for LangChain components! This
+template comes with files for each integration type, and you're welcome to duplicate or
+delete any of these files as needed (including the associated test files).
+
+To create any individual files from the [template], you can run e.g.:
+
+```bash
+langchain-cli integration new \
+ --name parrot-link \
+ --name-class ParrotLink \
+ --src integration_template/chat_models.py \
+ --dst langchain_parrot_link/chat_models_2.py
+```
+
+
+
+
+ Option 2: Poetry (manual)
+
+In this guide, we will be using [Poetry](https://python-poetry.org/) for
+dependency management and packaging, and you're welcome to use any other tools you prefer.
+
+### **Prerequisites**
+
+- [GitHub](https://github.com) account
+- [PyPi](https://pypi.org/) account
+
+### Boostrapping a new Python package with Poetry
+
+First, install Poetry:
+
+```bash
+pip install poetry
+```
+
+Next, come up with a name for your package. For this guide, we'll use `langchain-parrot-link`.
+You can confirm that the name is available on PyPi by searching for it on the [PyPi website](https://pypi.org/).
+
+Next, create your new Python package with Poetry, and navigate into the new directory with `cd`:
+
+```bash
+poetry new langchain-parrot-link
+cd langchain-parrot-link
+```
+
+Add main dependencies using Poetry, which will add them to your `pyproject.toml` file:
+
+```bash
+poetry add langchain-core
+```
+
+We will also add some `test` dependencies in a separate poetry dependency group. If
+you are not using Poetry, we recommend adding these in a way that won't package them
+with your published package, or just installing them separately when you run tests.
+
+`langchain-tests` will provide the [standard tests](../standard_tests) we will use later.
+We recommended pinning these to the latest version: 
+
+Note: Replace `` with the latest version of `langchain-tests` below.
+
+```bash
+poetry add --group test pytest pytest-socket pytest-asyncio langchain-tests==
+```
+
+And finally, have poetry set up a virtual environment with your dependencies, as well
+as your integration package:
+
+```bash
+poetry install --with test
+```
+
+You're now ready to start writing your integration package!
+
+### Writing your integration
+
+Let's say you're building a simple integration package that provides a `ChatParrotLink`
+chat model integration for LangChain. Here's a simple example of what your project
+structure might look like:
+
+```plaintext
+langchain-parrot-link/
+├── langchain_parrot_link/
+│ ├── __init__.py
+│ └── chat_models.py
+├── tests/
+│ ├── __init__.py
+│ └── test_chat_models.py
+├── pyproject.toml
+└── README.md
+```
+
+All of these files should already exist from step 1, except for
+`chat_models.py` and `test_chat_models.py`! We will implement `test_chat_models.py`
+later, following the [standard tests](../standard_tests) guide.
+
+For `chat_models.py`, simply paste the contents of the chat model implementation
+[above](#implementing-langchain-components).
+
+
+
+### Push your package to a public Github repository
+
+This is only required if you want to publish your integration in the LangChain documentation.
+
+1. Create a new repository on GitHub.
+2. Push your code to the repository.
+3. Confirm that your repository is viewable by the public (e.g. in a private browsing window, where you're not logged into Github).
## Implementing LangChain components
@@ -37,11 +206,15 @@ import CodeBlock from '@theme/CodeBlock';
Refer to the [Custom Chat Model Guide](/docs/how_to/custom_chat_model) guide for
detail on a starter chat model [implementation](/docs/how_to/custom_chat_model/#implementation).
- The `langchain-cli` package contains [template integrations](https://github.com/langchain-ai/langchain/tree/master/libs/cli/langchain_cli/integration_template/integration_template)
- for major LangChain components that are tested against the standard unit and
- integration tests in the LangChain Github repository. You can access the starter
- chat model implementation [here](https://github.com/langchain-ai/langchain/blob/master/libs/cli/langchain_cli/integration_template/integration_template/chat_models.py).
- For convenience, we also include the code below.
+ You can start from the following template or langchain-cli command:
+
+ ```bash
+ langchain-cli integration new \
+ --name parrot-link \
+ --name-class ParrotLink \
+ --src integration_template/chat_models.py \
+ --dst langchain_parrot_link/chat_models.py
+ ```
Example chat model code
@@ -150,11 +323,15 @@ implement this method to handle that.
### Implementation
-The `langchain-cli` package contains [template integrations](https://github.com/langchain-ai/langchain/tree/master/libs/cli/langchain_cli/integration_template/integration_template)
-for major LangChain components that are tested against the standard unit and
-integration tests in the LangChain Github repository. You can access the starter
-embedding model implementation [here](https://github.com/langchain-ai/langchain/blob/master/libs/cli/langchain_cli/integration_template/integration_template/embeddings.py).
-For convenience, we also include the code below.
+You can start from the following template or langchain-cli command:
+
+```bash
+langchain-cli integration new \
+ --name parrot-link \
+ --name-class ParrotLink \
+ --src integration_template/embeddings.py \
+ --dst langchain_parrot_link/embeddings.py
+```
Example embeddings code
@@ -223,11 +400,15 @@ this method to run the tool asynchronously in addition to `_run`.
### Implementation
-The `langchain-cli` package contains [template integrations](https://github.com/langchain-ai/langchain/tree/master/libs/cli/langchain_cli/integration_template/integration_template)
-for major LangChain components that are tested against the standard unit and
-integration tests in the LangChain Github repository. You can access the starter
-embedding model implementation [here](https://github.com/langchain-ai/langchain/blob/master/libs/cli/langchain_cli/integration_template/integration_template/tools.py).
-For convenience, we also include the code below.
+You can start from the following template or langchain-cli command:
+
+```bash
+langchain-cli integration new \
+ --name parrot-link \
+ --name-class ParrotLink \
+ --src integration_template/tools.py \
+ --dst langchain_parrot_link/tools.py
+```
Example tool code
@@ -286,11 +467,15 @@ in addition to `_get_relevant_documents` for performance reasons.
### Implementation
-The `langchain-cli` package contains [template integrations](https://github.com/langchain-ai/langchain/tree/master/libs/cli/langchain_cli/integration_template/integration_template)
-for major LangChain components that are tested against the standard unit and
-integration tests in the LangChain Github repository. You can access the starter
-embedding model implementation [here](https://github.com/langchain-ai/langchain/blob/master/libs/cli/langchain_cli/integration_template/integration_template/retrievers.py).
-For convenience, we also include the code below.
+You can start from the following template or langchain-cli command:
+
+```bash
+langchain-cli integration new \
+ --name parrot-link \
+ --name-class ParrotLink \
+ --src integration_template/retrievers.py \
+ --dst langchain_parrot_link/retrievers.py
+```
Example retriever code
@@ -313,95 +498,6 @@ import RetrieverSource from '/src/theme/integration_template/integration_templat
---
-## (Optional) bootstrapping a new integration package
-
-In this guide, we will be using [Poetry](https://python-poetry.org/) for
-dependency management and packaging, and you're welcome to use any other tools you prefer.
-
-### **Prerequisites**
-
-- [GitHub](https://github.com) account
-- [PyPi](https://pypi.org/) account
-
-### Boostrapping a new Python package with Poetry
-
-First, install Poetry:
-
-```bash
-pip install poetry
-```
-
-Next, come up with a name for your package. For this guide, we'll use `langchain-parrot-link`.
-You can confirm that the name is available on PyPi by searching for it on the [PyPi website](https://pypi.org/).
-
-Next, create your new Python package with Poetry, and navigate into the new directory with `cd`:
-
-```bash
-poetry new langchain-parrot-link
-cd langchain-parrot-link
-```
-
-Add main dependencies using Poetry, which will add them to your `pyproject.toml` file:
-
-```bash
-poetry add langchain-core
-```
-
-We will also add some `test` dependencies in a separate poetry dependency group. If
-you are not using Poetry, we recommend adding these in a way that won't package them
-with your published package, or just installing them separately when you run tests.
-
-`langchain-tests` will provide the [standard tests](../standard_tests) we will use later.
-We recommended pinning these to the latest version:
-
-Note: Replace `` with the latest version of `langchain-tests` below.
-
-```bash
-poetry add --group test pytest pytest-socket pytest-asyncio langchain-tests==
-```
-
-And finally, have poetry set up a virtual environment with your dependencies, as well
-as your integration package:
-
-```bash
-poetry install --with test
-```
-
-You're now ready to start writing your integration package!
-
-### Writing your integration
-
-Let's say you're building a simple integration package that provides a `ChatParrotLink`
-chat model integration for LangChain. Here's a simple example of what your project
-structure might look like:
-
-```plaintext
-langchain-parrot-link/
-├── langchain_parrot_link/
-│ ├── __init__.py
-│ └── chat_models.py
-├── tests/
-│ ├── __init__.py
-│ └── test_chat_models.py
-├── pyproject.toml
-└── README.md
-```
-
-All of these files should already exist from step 1, except for
-`chat_models.py` and `test_chat_models.py`! We will implement `test_chat_models.py`
-later, following the [standard tests](../standard_tests) guide.
-
-For `chat_models.py`, simply paste the contents of the chat model implementation
-[above](#implementing-langchain-components).
-
-### Push your package to a public Github repository
-
-This is only required if you want to publish your integration in the LangChain documentation.
-
-1. Create a new repository on GitHub.
-2. Push your code to the repository.
-3. Confirm that your repository is viewable by the public (e.g. in a private browsing window, where you're not logged into Github).
-
## Next Steps
Now that you've implemented your package, you can move on to [testing your integration](../standard_tests) for your integration and successfully run them.
diff --git a/docs/docs/contributing/how_to/integrations/standard_tests.mdx b/docs/docs/contributing/how_to/integrations/standard_tests.mdx
index d3f0dec054014..5462b966a6404 100644
--- a/docs/docs/contributing/how_to/integrations/standard_tests.mdx
+++ b/docs/docs/contributing/how_to/integrations/standard_tests.mdx
@@ -8,12 +8,10 @@ When creating either a custom class for yourself or to publish in a LangChain in
## Setup
-If you're coming from the [previous guide](../package), you have already installed these dependencies, and you can skip this section.
-
First, let's install 2 dependencies:
- `langchain-core` will define the interfaces we want to import to define our custom tool.
-- `langchain-tests` will provide the standard tests we want to use. Recommended to pin to the latest version:
+- `langchain-tests` will provide the standard tests we want to use, as well as pytest plugins necessary to run them. Recommended to pin to the latest version:
:::note
@@ -31,13 +29,13 @@ If you followed the [previous guide](../package), you should already have these
```bash
poetry add langchain-core
-poetry add --group test pytest pytest-socket pytest-asyncio langchain-tests==
+poetry add --group test langchain-tests==
poetry install --with test
```
```bash
-pip install -U langchain-core pytest pytest-socket pytest-asyncio langchain-tests
+pip install -U langchain-core langchain-tests
# install current package in editable mode
pip install --editable .
@@ -45,28 +43,6 @@ pip install --editable .
-Let's say we're publishing a package, `langchain_parrot_link`, that exposes the chat model from the [guide on implementing the package](../package). We can add the standard tests to the package by following the steps below.
-
-And we'll assume you've structured your package the same way as the main LangChain
-packages:
-
-```plaintext
-langchain-parrot-link/
-├── langchain_parrot_link/
-│ ├── __init__.py
-│ └── chat_models.py
-├── tests/
-│ ├── __init__.py
-│ ├── unit_tests/
-│ │ ├── __init__.py
-│ │ └── test_chat_models.py
-│ └── integration_tests/
-│ ├── __init__.py
-│ └── test_chat_models.py
-├── pyproject.toml
-└── README.md
-```
-
## Add and configure standard tests
There are 2 namespaces in the `langchain-tests` package:
@@ -79,6 +55,12 @@ Both types of tests are implemented as [`pytest` class-based test suites](https:
By subclassing the base classes for each type of standard test (see below), you get all of the standard tests for that type, and you
can override the properties that the test suite uses to configure the tests.
+In order to run the tests in the same way as this guide, we recommend subclassing these
+classes in test files under two test subdirectories:
+
+- `tests/unit_tests` for unit tests
+- `tests/integration_tests` for integration tests
+
### Implementing standard tests
import CodeBlock from '@theme/CodeBlock';
@@ -90,17 +72,22 @@ each component type:
-Here's how you would configure the standard unit tests for the custom chat model:
+To configure standard tests for a chat model, we subclass `ChatModelUnitTests` and `ChatModelIntegrationTests`. On each subclass, we override the following `@property` methods to specify the chat model to be tested and the chat model's configuration:
+| Property | Description |
+| --- | --- |
+| `chat_model_class` | The class for the chat model to be tested |
+| `chat_model_params` | The parameters to pass to the chat
+model's constructor |
-Chat model standard tests test a range of behaviors, from the most basic requirements (generating a response to a query) to optional capabilities like multi-modal support and tool-calling. For a test run to be successful:
+Additionally, chat model standard tests test a range of behaviors, from the most basic requirements (generating a response to a query) to optional capabilities like multi-modal support and tool-calling. For a test run to be successful:
1. If a feature is intended to be supported by the model, it should pass;
2. If a feature is not intended to be supported by the model, it should be skipped.
Tests for "optional" capabilities are controlled via a set of properties that can be overridden on the test model subclass.
-You can see the entire list of properties in the API references for
+You can see the **entire list of configurable capabilities** in the API references for
[unit tests](https://python.langchain.com/api_reference/standard_tests/unit_tests/langchain_tests.unit_tests.chat_models.ChatModelUnitTests.html)
and [integration tests](https://python.langchain.com/api_reference/standard_tests/integration_tests/langchain_tests.integration_tests.chat_models.ChatModelIntegrationTests.html).
@@ -157,8 +144,7 @@ import ChatIntegrationSource from '../../../../src/theme/integration_template/te
Here's how you would configure the standard tests for a typical vector store (using
`ParrotVectorStore` as a placeholder):
-Note that unlike chat models, vector stores do not have optional capabilities that
-can be enabled or disabled at this time.
+Vector store tests do not have optional capabilities to be configured at this time.
import VectorStoreIntegrationSource from '../../../../src/theme/integration_template/tests/integration_tests/test_vectorstores.py';
@@ -174,6 +160,10 @@ import VectorStoreIntegrationSource from '../../../../src/theme/integration_temp
Configuring the tests consists of implementing pytest fixtures for setting up an
empty vector store and tearing down the vector store after the test run ends.
+| Fixture | Description |
+| --- | --- |
+| `vectorstore` | A generator that yields an empty vector store for unit tests. The vector store is cleaned up after the test run ends. |
+
For example, below is the `VectorStoreIntegrationTests` class for the [Chroma](https://python.langchain.com/docs/integrations/vectorstores/chroma/)
integration:
@@ -220,11 +210,12 @@ Details on what tests are run and troubleshooting tips for each test can be foun
-To configure standard tests for an embeddings model, we subclass
-`EmbeddingsUnitTests` and `EmbeddingsIntegrationTests`. On each subclass, we
-implement the `embeddings_class` property to specify the embeddings model to be
-tested. We can also override the embedding_model_params property to specify
-initialization parameters. See examples below.
+To configure standard tests for an embeddings model, we subclass `EmbeddingsUnitTests` and `EmbeddingsIntegrationTests`. On each subclass, we override the following `@property` methods to specify the embeddings model to be tested and the embeddings model's configuration:
+
+| Property | Description |
+| --- | --- |
+| `embeddings_class` | The class for the embeddings model to be tested |
+| `embedding_model_params` | The parameters to pass to the embeddings model's constructor |
:::note