github/langchain
1
0
Fork 0
mirror of https://github.com/hwchase17/langchain.git synced 2025-06-21 14:18:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: more integration contrib (#28618)

Browse Source
This commit is contained in:
Erick Friis 2024-12-08 21:41:08 -08:00 committed by GitHub
parent eabe587787
commit b53f07bfb9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 235 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

318
docs/docs/contributing/how_to/integrations/package.mdx
View File

@ -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.
<details>
<summary>Option 1: langchain-cli (recommended)</summary>
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
```
</details>
<details>
<summary>Option 2: Poetry (manual)</summary>
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: <img src="https://img.shields.io/pypi/v/langchain-tests" style={{position:"relative",top:4,left:3}} />
Note: Replace `<latest_version>` with the latest version of `langchain-tests` below.
```bash
poetry add --group test pytest pytest-socket pytest-asyncio langchain-tests==<latest_version>
```
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).
</details>
### 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
```
<details>
<summary>Example chat model code</summary>
@ -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
```
<details>
<summary>Example embeddings code</summary>
@ -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
```
<details>
<summary>Example tool code</summary>
@ -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
```
<details>
<summary>Example retriever code</summary>
@ -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: <img src="https://img.shields.io/pypi/v/langchain-tests" style={{position:"relative",top:4,left:3}} />
Note: Replace `<latest_version>` with the latest version of `langchain-tests` below.
```bash
poetry add --group test pytest pytest-socket pytest-asyncio langchain-tests==<latest_version>
```
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.

65
docs/docs/contributing/how_to/integrations/standard_tests.mdx
View File

@ -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: <img src="https://img.shields.io/pypi/v/langchain-tests" style={{position:"relative",top:4,left:3}} />
- `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: <img src="https://img.shields.io/pypi/v/langchain-tests" style={{position:"relative",top:4,left:3}} />
:::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==<latest_version>
poetry add --group test langchain-tests==<latest_version>
poetry install --with test
```
</TabItem>
<TabItem value="pip" label="Pip">
```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 .
</TabItem>
</Tabs>
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:
<TabItem value="chat_models" label="Chat models">
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
</TabItem>
<TabItem value="embeddings" label="Embeddings">
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