mirror of https://github.com/hwchase17/langchain
docs: developer docs (#14776)
Builds out a developer documentation section in the docs - Links it from contributing.md - Adds an initial guide on how to contribute an integration --------- Co-authored-by: Bagatur <baskaryan@gmail.com>pull/14826/head
Erick Friis
5 months ago
committed by
GitHub
parent
01693b291e
commit
8a07c56313
@ -1,49 +1,3 @@
|
||||
# Website
|
||||
# LangChain Documentation
|
||||
|
||||
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
|
||||
|
||||
### Installation
|
||||
|
||||
```
|
||||
$ yarn
|
||||
```
|
||||
|
||||
### Local Development
|
||||
|
||||
```
|
||||
$ yarn start
|
||||
```
|
||||
|
||||
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
|
||||
|
||||
### Build
|
||||
|
||||
```
|
||||
$ yarn build
|
||||
```
|
||||
|
||||
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
||||
|
||||
### Deployment
|
||||
|
||||
Using SSH:
|
||||
|
||||
```
|
||||
$ USE_SSH=true yarn deploy
|
||||
```
|
||||
|
||||
Not using SSH:
|
||||
|
||||
```
|
||||
$ GIT_USER=<Your GitHub username> yarn deploy
|
||||
```
|
||||
|
||||
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
Some common defaults for linting/formatting have been set for you. If you integrate your project with an open-source Continuous Integration system (e.g. Travis CI, CircleCI), you may check for issues using the following command.
|
||||
|
||||
```
|
||||
$ yarn ci
|
||||
```
|
||||
For more information on contributing to our documentation, see the [Documentation Contributing Guide](https://python.langchain.com/docs/contributing/documentation)
|
||||
|
||||
@ -0,0 +1,250 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
# Contribute Code
|
||||
|
||||
To contribute to this project, please follow the ["fork and pull request"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow.
|
||||
Please do not try to push directly to this repo unless you are a maintainer.
|
||||
|
||||
Please follow the checked-in pull request template when opening pull requests. Note related issues and tag relevant
|
||||
maintainers.
|
||||
|
||||
Pull requests cannot land without passing the formatting, linting, and testing checks first. See [Testing](#testing) and
|
||||
[Formatting and Linting](#formatting-and-linting) for how to run these checks locally.
|
||||
|
||||
It's essential that we maintain great documentation and testing. If you:
|
||||
- Fix a bug
|
||||
- Add a relevant unit or integration test when possible. These live in `tests/unit_tests` and `tests/integration_tests`.
|
||||
- Make an improvement
|
||||
- Update any affected example notebooks and documentation. These live in `docs`.
|
||||
- Update unit and integration tests when relevant.
|
||||
- Add a feature
|
||||
- Add a demo notebook in `docs/docs/`.
|
||||
- Add unit and integration tests.
|
||||
|
||||
We are a small, progress-oriented team. If there's something you'd like to add or change, opening a pull request is the
|
||||
best way to get our attention.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
This quick start guide explains how to run the repository locally.
|
||||
For a [development container](https://containers.dev/), see the [.devcontainer folder](https://github.com/langchain-ai/langchain/tree/master/.devcontainer).
|
||||
|
||||
### Dependency Management: Poetry and other env/dependency managers
|
||||
|
||||
This project utilizes [Poetry](https://python-poetry.org/) v1.6.1+ as a dependency manager.
|
||||
|
||||
❗Note: *Before installing Poetry*, if you use `Conda`, create and activate a new Conda env (e.g. `conda create -n langchain python=3.9`)
|
||||
|
||||
Install Poetry: **[documentation on how to install it](https://python-poetry.org/docs/#installation)**.
|
||||
|
||||
❗Note: If you use `Conda` or `Pyenv` as your environment/package manager, after installing Poetry,
|
||||
tell Poetry to use the virtualenv python environment (`poetry config virtualenvs.prefer-active-python true`)
|
||||
|
||||
### Different packages
|
||||
|
||||
This repository contains multiple packages:
|
||||
- `langchain-core`: Base interfaces for key abstractions as well as logic for combining them in chains (LangChain Expression Language).
|
||||
- `langchain-community`: Third-party integrations of various components.
|
||||
- `langchain`: Chains, agents, and retrieval logic that makes up the cognitive architecture of your applications.
|
||||
- `langchain-experimental`: Components and chains that are experimental, either in the sense that the techniques are novel and still being tested, or they require giving the LLM more access than would be possible in most production systems.
|
||||
- Partner integrations: Partner packages in `libs/partners` that are independently version controlled.
|
||||
|
||||
Each of these has its own development environment. Docs are run from the top-level makefile, but development
|
||||
is split across separate test & release flows.
|
||||
|
||||
For this quickstart, start with langchain-community:
|
||||
|
||||
```bash
|
||||
cd libs/community
|
||||
```
|
||||
|
||||
### Local Development Dependencies
|
||||
|
||||
Install langchain-community development requirements (for running langchain, running examples, linting, formatting, tests, and coverage):
|
||||
|
||||
```bash
|
||||
poetry install --with lint,typing,test,integration_tests
|
||||
```
|
||||
|
||||
Then verify dependency installation:
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
If during installation you receive a `WheelFileValidationError` for `debugpy`, please make sure you are running
|
||||
Poetry v1.6.1+. This bug was present in older versions of Poetry (e.g. 1.4.1) and has been resolved in newer releases.
|
||||
If you are still seeing this bug on v1.6.1, you may also try disabling "modern installation"
|
||||
(`poetry config installer.modern-installation false`) and re-installing requirements.
|
||||
See [this `debugpy` issue](https://github.com/microsoft/debugpy/issues/1246) for more details.
|
||||
|
||||
### Testing
|
||||
|
||||
_In `langchain`, `langchain-community`, and `langchain-experimental`, some test dependencies are optional; see section about optional dependencies_.
|
||||
|
||||
Unit tests cover modular logic that does not require calls to outside APIs.
|
||||
If you add new logic, please add a unit test.
|
||||
|
||||
To run unit tests:
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
To run unit tests in Docker:
|
||||
|
||||
```bash
|
||||
make docker_tests
|
||||
```
|
||||
|
||||
There are also [integration tests and code-coverage](./testing) available.
|
||||
|
||||
### Only develop langchain_core or langchain_experimental
|
||||
|
||||
If you are only developing `langchain_core` or `langchain_experimental`, you can simply install the dependencies for the respective projects and run tests:
|
||||
|
||||
```bash
|
||||
cd libs/core
|
||||
poetry install --with test
|
||||
make test
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```bash
|
||||
cd libs/experimental
|
||||
poetry install --with test
|
||||
make test
|
||||
```
|
||||
|
||||
### Formatting and Linting
|
||||
|
||||
Run these locally before submitting a PR; the CI system will check also.
|
||||
|
||||
#### Code Formatting
|
||||
|
||||
Formatting for this project is done via [ruff](https://docs.astral.sh/ruff/rules/).
|
||||
|
||||
To run formatting for docs, cookbook and templates:
|
||||
|
||||
```bash
|
||||
make format
|
||||
```
|
||||
|
||||
To run formatting for a library, run the same command from the relevant library directory:
|
||||
|
||||
```bash
|
||||
cd libs/{LIBRARY}
|
||||
make format
|
||||
```
|
||||
|
||||
Additionally, you can run the formatter only on the files that have been modified in your current branch as compared to the master branch using the format_diff command:
|
||||
|
||||
```bash
|
||||
make format_diff
|
||||
```
|
||||
|
||||
This is especially useful when you have made changes to a subset of the project and want to ensure your changes are properly formatted without affecting the rest of the codebase.
|
||||
|
||||
#### Linting
|
||||
|
||||
Linting for this project is done via a combination of [ruff](https://docs.astral.sh/ruff/rules/) and [mypy](http://mypy-lang.org/).
|
||||
|
||||
To run linting for docs, cookbook and templates:
|
||||
|
||||
```bash
|
||||
make lint
|
||||
```
|
||||
|
||||
To run linting for a library, run the same command from the relevant library directory:
|
||||
|
||||
```bash
|
||||
cd libs/{LIBRARY}
|
||||
make lint
|
||||
```
|
||||
|
||||
In addition, you can run the linter only on the files that have been modified in your current branch as compared to the master branch using the lint_diff command:
|
||||
|
||||
```bash
|
||||
make lint_diff
|
||||
```
|
||||
|
||||
This can be very helpful when you've made changes to only certain parts of the project and want to ensure your changes meet the linting standards without having to check the entire codebase.
|
||||
|
||||
We recognize linting can be annoying - if you do not want to do it, please contact a project maintainer, and they can help you with it. We do not want this to be a blocker for good code getting contributed.
|
||||
|
||||
#### Spellcheck
|
||||
|
||||
Spellchecking for this project is done via [codespell](https://github.com/codespell-project/codespell).
|
||||
Note that `codespell` finds common typos, so it could have false-positive (correctly spelled but rarely used) and false-negatives (not finding misspelled) words.
|
||||
|
||||
To check spelling for this project:
|
||||
|
||||
```bash
|
||||
make spell_check
|
||||
```
|
||||
|
||||
To fix spelling in place:
|
||||
|
||||
```bash
|
||||
make spell_fix
|
||||
```
|
||||
|
||||
If codespell is incorrectly flagging a word, you can skip spellcheck for that word by adding it to the codespell config in the `pyproject.toml` file.
|
||||
|
||||
```python
|
||||
[tool.codespell]
|
||||
...
|
||||
# Add here:
|
||||
ignore-words-list = 'momento,collison,ned,foor,reworkd,parth,whats,aapply,mysogyny,unsecure'
|
||||
```
|
||||
|
||||
## Working with Optional Dependencies
|
||||
|
||||
`langchain`, `langchain-community`, and `langchain-experimental` rely on optional dependencies to keep these packages lightweight.
|
||||
|
||||
`langchain-core` and partner packages **do not use** optional dependencies in this way.
|
||||
|
||||
You only need to add a new dependency if a **unit test** relies on the package.
|
||||
If your package is only required for **integration tests**, then you can skip these
|
||||
steps and leave all pyproject.toml and poetry.lock files alone.
|
||||
|
||||
If you're adding a new dependency to Langchain, assume that it will be an optional dependency, and
|
||||
that most users won't have it installed.
|
||||
|
||||
Users who do not have the dependency installed should be able to **import** your code without
|
||||
any side effects (no warnings, no errors, no exceptions).
|
||||
|
||||
To introduce the dependency to the pyproject.toml file correctly, please do the following:
|
||||
|
||||
1. Add the dependency to the main group as an optional dependency
|
||||
```bash
|
||||
poetry add --optional [package_name]
|
||||
```
|
||||
2. Open pyproject.toml and add the dependency to the `extended_testing` extra
|
||||
3. Relock the poetry file to update the extra.
|
||||
```bash
|
||||
poetry lock --no-update
|
||||
```
|
||||
4. Add a unit test that the very least attempts to import the new code. Ideally, the unit
|
||||
test makes use of lightweight fixtures to test the logic of the code.
|
||||
5. Please use the `@pytest.mark.requires(package_name)` decorator for any tests that require the dependency.
|
||||
|
||||
## Adding a Jupyter Notebook
|
||||
|
||||
If you are adding a Jupyter Notebook example, you'll want to install the optional `dev` dependencies.
|
||||
|
||||
To install dev dependencies:
|
||||
|
||||
```bash
|
||||
poetry install --with dev
|
||||
```
|
||||
|
||||
Launch a notebook:
|
||||
|
||||
```bash
|
||||
poetry run jupyter notebook
|
||||
```
|
||||
|
||||
When you run `poetry install`, the `langchain` package is installed as editable in the virtualenv, so your new logic can be imported into the notebook.
|
||||
@ -0,0 +1,67 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
# Contribute Documentation
|
||||
|
||||
The docs directory contains Documentation and API Reference.
|
||||
|
||||
Documentation is built using [Quarto](https://quarto.org) and [Docusaurus 2](https://docusaurus.io/).
|
||||
|
||||
API Reference are largely autogenerated by [sphinx](https://www.sphinx-doc.org/en/master/) from the code and are hosted by [Read the Docs](https://readthedocs.org/).
|
||||
For that reason, we ask that you add good documentation to all classes and methods.
|
||||
|
||||
Similar to linting, we recognize documentation can be annoying. If you do not want to do it, please contact a project maintainer, and they can help you with it. We do not want this to be a blocker for good code getting contributed.
|
||||
|
||||
## Build Documentation Locally
|
||||
|
||||
### Install dependencies
|
||||
|
||||
- [Quarto](https://quarto.org) - package that converts Jupyter notebooks (`.ipynb` files) into mdx files for serving in Docusaurus.
|
||||
- `poetry install` from the monorepo root
|
||||
|
||||
### Building
|
||||
|
||||
In the following commands, the prefix `api_` indicates that those are operations for the API Reference.
|
||||
|
||||
Before building the documentation, it is always a good idea to clean the build directory:
|
||||
|
||||
```bash
|
||||
make docs_clean
|
||||
make api_docs_clean
|
||||
```
|
||||
|
||||
Next, you can build the documentation as outlined below:
|
||||
|
||||
```bash
|
||||
make docs_build
|
||||
make api_docs_build
|
||||
```
|
||||
|
||||
Finally, run the link checker to ensure all links are valid:
|
||||
|
||||
```bash
|
||||
make docs_linkcheck
|
||||
make api_docs_linkcheck
|
||||
```
|
||||
|
||||
### Linting and Formatting
|
||||
|
||||
The docs are linted from the monorepo root. To lint the docs, run the following from there:
|
||||
|
||||
```bash
|
||||
poetry install --with lint,typing
|
||||
make lint
|
||||
```
|
||||
|
||||
If you have formatting-related errors, you can fix them automatically with:
|
||||
|
||||
```bash
|
||||
make format
|
||||
```
|
||||
|
||||
## Verify Documentation changes
|
||||
|
||||
After pushing documentation changes to the repository, you can preview and verify that the changes are
|
||||
what you wanted by clicking the `View deployment` or `Visit Preview` buttons on the pull request `Conversation` page.
|
||||
This will take you to a preview of the documentation changes.
|
||||
This preview is created by [Vercel](https://vercel.com/docs/getting-started-with-vercel).
|
||||
@ -0,0 +1,42 @@
|
||||
---
|
||||
sidebar_position: 0
|
||||
---
|
||||
# Welcome Contributors
|
||||
|
||||
Hi there! Thank you for even being interested in contributing to LangChain.
|
||||
As an open-source project in a rapidly developing field, we are extremely open to contributions, whether they involve new features, improved infrastructure, better documentation, or bug fixes.
|
||||
|
||||
## 🗺️ Guidelines
|
||||
|
||||
### 👩💻 Ways to contribute
|
||||
|
||||
There are many ways to contribute to LangChain. Here are some common ways people contribute:
|
||||
|
||||
- [**Documentation**](./documentation): Help improve our docs, including this one!
|
||||
- [**Code**](./code): Help us write code, fix bugs, or improve our infrastructure.
|
||||
- [**Integrations**](./integration): Help us integrate with your favorite vendors and tools.
|
||||
|
||||
### 🚩GitHub Issues
|
||||
|
||||
Our [issues](https://github.com/langchain-ai/langchain/issues) page is kept up to date with bugs, improvements, and feature requests.
|
||||
|
||||
There is a taxonomy of labels to help with sorting and discovery of issues of interest. Please use these to help organize issues.
|
||||
|
||||
If you start working on an issue, please assign it to yourself.
|
||||
|
||||
If you are adding an issue, please try to keep it focused on a single, modular bug/improvement/feature.
|
||||
If two issues are related, or blocking, please link them rather than combining them.
|
||||
|
||||
We will try to keep these issues as up-to-date as possible, though
|
||||
with the rapid rate of development in this field some may get out of date.
|
||||
If you notice this happening, please let us know.
|
||||
|
||||
### 🙋Getting Help
|
||||
|
||||
Our goal is to have the simplest developer setup possible. Should you experience any difficulty getting setup, please
|
||||
contact a maintainer! Not only do we want to help get you unblocked, but we also want to make sure that the process is
|
||||
smooth for future contributors.
|
||||
|
||||
In a similar vein, we do enforce certain linting, formatting, and documentation standards in the codebase.
|
||||
If you are finding these difficult (or even just annoying) to work with, feel free to contact a maintainer for help -
|
||||
we do not want these to get in the way of getting good code into the codebase.
|
||||
@ -0,0 +1,148 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
# Contribute Integrations
|
||||
|
||||
To begin, make sure you have all the dependencies outlined in guide on [Contributing Code](./code).
|
||||
|
||||
There are a few different places you can contribute integrations for LangChain:
|
||||
|
||||
- **Community**: For lighter-weight integrations that are primarily maintained by LangChain and the Open Source Community.
|
||||
- **Partner Packages**: For independent packages that are co-maintained by LangChain and a partner.
|
||||
|
||||
For the most part, new integrations should be added to the Community package. Partner packages require more maintenance as separate packages, so please confirm with the LangChain team before creating a new partner package.
|
||||
|
||||
In the following sections, we'll walk through how to contribute to each of these packages from a fake company, `Parrot Link AI`.
|
||||
|
||||
## Community Package
|
||||
|
||||
The `langchain-community` package is in `libs/community` and contains most integrations.
|
||||
|
||||
It is installed by users with `pip install langchain-community`, and exported members can be imported with code like
|
||||
|
||||
```python
|
||||
from langchain_community.chat_models import ParrotLinkLLM
|
||||
from langchain_community.llms import ChatParrotLink
|
||||
from langchain_community.vectorstores import ParrotLinkVectorStore
|
||||
```
|
||||
|
||||
The community package relies on manually-installed dependent packages, so you will see errors if you try to import a package that is not installed. In our fake example, if you tried to import `ParrotLinkLLM` without installing `parrot-link-sdk`, you will see an `ImportError` telling you to install it when trying to use it.
|
||||
|
||||
Let's say we wanted to implement a chat model for Parrot Link AI. We would create a new file in `libs/community/langchain_community/chat_models/parrot_link.py` with the following code:
|
||||
|
||||
```python
|
||||
from langchain_core.language_models.chat_models import BaseChatModel
|
||||
|
||||
class ChatParrotLink(BaseChatModel):
|
||||
"""ChatParrotLink chat model.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
|
||||
from langchain_parrot_link import ChatParrotLink
|
||||
|
||||
model = ChatParrotLink()
|
||||
"""
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
And we would write tests in:
|
||||
|
||||
- Unit tests: `libs/community/tests/unit_tests/chat_models/test_parrot_link.py`
|
||||
- Integration tests: `libs/community/tests/integration_tests/chat_models/test_parrot_link.py`
|
||||
|
||||
And add documentation to:
|
||||
- `docs/docs/integrations/chat/parrot_link.ipynb`
|
||||
|
||||
- `docs/docs/
|
||||
## Partner Packages
|
||||
|
||||
Partner packages are in `libs/partners/*` and are installed by users with `pip install langchain-{partner}`, and exported members can be imported with code like
|
||||
|
||||
```python
|
||||
from langchain_{partner} import X
|
||||
```
|
||||
|
||||
### Set up a new package
|
||||
|
||||
To set up a new partner package, use the latest version of the LangChain CLI. You can install or update it with:
|
||||
|
||||
```bash
|
||||
pip install -U langchain-cli
|
||||
```
|
||||
|
||||
Let's say you want to create a new partner package working for a company called Parrot Link AI.
|
||||
|
||||
Then, run the following command to create a new partner package:
|
||||
|
||||
```bash
|
||||
cd libs/partners
|
||||
langchain-cli integration new
|
||||
> Name: parrot-link
|
||||
> Name of integration in PascalCase [ParrotLink]: ParrotLink
|
||||
```
|
||||
|
||||
This will create a new package in `libs/partners/parrot-link` with the following structure:
|
||||
|
||||
```
|
||||
libs/partners/parrot-link/
|
||||
langchain_parrot_link/ # folder containing your package
|
||||
...
|
||||
tests/
|
||||
...
|
||||
docs/ # bootstrapped docs notebooks, must be moved to /docs in monorepo root
|
||||
...
|
||||
scripts/ # scripts for CI
|
||||
...
|
||||
LICENSE
|
||||
README.md # fill out with information about your package
|
||||
Makefile # default commands for CI
|
||||
pyproject.toml # package metadata, mostly managed by Poetry
|
||||
poetry.lock # package lockfile, managed by Poetry
|
||||
.gitignore
|
||||
```
|
||||
|
||||
### Implement your package
|
||||
|
||||
First, add any dependencies your package needs, such as your company's SDK:
|
||||
|
||||
```bash
|
||||
poetry add parrot-link-sdk
|
||||
```
|
||||
|
||||
If you need separate dependencies for type checking, you can add them to the `typing` group with:
|
||||
|
||||
```bash
|
||||
poetry add --group typing types-parrot-link-sdk
|
||||
```
|
||||
|
||||
Then, implement your package in `libs/partners/parrot-link/langchain_parrot_link`.
|
||||
|
||||
By default, this will include stubs for a Chat Model, an LLM, and/or a Vector Store. You should delete any of the files you won't use and remove them from `__init__.py`.
|
||||
|
||||
### Write Unit and Integration Tests
|
||||
|
||||
Some basic tests are generated in the tests/ directory. You should add more tests to cover your package's functionality.
|
||||
|
||||
For information on running and implementing tests, see the [Testing guide](./testing).
|
||||
|
||||
### Write documentation
|
||||
|
||||
Documentation is generated from Jupyter notebooks in the `docs/` directory. You should move the generated notebooks to the relevant `docs/docs/integrations` directory in the monorepo root.
|
||||
|
||||
### Additional steps
|
||||
|
||||
Contributor steps:
|
||||
|
||||
- [ ] Add the new package to the API reference dropdown in `docs/api_reference/themes/scikit-learn-modern/nav.html`
|
||||
- [ ] Add package (e.g. `langchain-parrot-link`) to API docs build in `docs/api_reference/requirements.txt`
|
||||
- [ ] Add secret names to manual integrations workflow in `.github/workflows/_integration_test.yml`
|
||||
- [ ] Add secrets to release workflow (for pre-release testing) in `.github/workflows/_release.yml`
|
||||
- [ ] Add library choice to top of `.github/workflows/_release.yml`
|
||||
|
||||
Maintainer steps (Contributors should **not** do these):
|
||||
|
||||
- [ ] set up pypi and test pypi projects
|
||||
- [ ] add credential secrets to Github Actions
|
||||
- [ ] add package to conda-forge
|
||||
@ -0,0 +1,56 @@
|
||||
---
|
||||
sidebar_label: Package Versioning
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# 📕 Package Versioning
|
||||
|
||||
As of now, LangChain has an ad hoc release process: releases are cut with high frequency by
|
||||
a maintainer and published to [PyPI](https://pypi.org/).
|
||||
The different packages are versioned slightly differently.
|
||||
|
||||
## `langchain-core`
|
||||
|
||||
`langchain-core` is currently on version `0.1.x`.
|
||||
|
||||
As `langchain-core` contains the base abstractions and runtime for the whole LangChain ecosystem, we will communicate any breaking changes with advance notice and version bumps. The exception for this is anything in `langchain_core.beta`. The reason for `langchain_core.beta` is that given the rate of change of the field, being able to move quickly is still a priority, and this module is our attempt to do so.
|
||||
|
||||
Minor version increases will occur for:
|
||||
|
||||
- Breaking changes for any public interfaces NOT in `langchain_core.beta`
|
||||
|
||||
Patch version increases will occur for:
|
||||
|
||||
- Bug fixes
|
||||
- New features
|
||||
- Any changes to private interfaces
|
||||
- Any changes to `langchain_core.beta`
|
||||
|
||||
## `langchain`
|
||||
|
||||
`langchain` is currently on version `0.0.x`
|
||||
|
||||
All changes will be accompanied by a patch version increase. Any changes to public interfaces are nearly always done in a backwards compatible way and will be communicated ahead of time when they are not backwards compatible.
|
||||
|
||||
We are targeting January 2024 for a release of `langchain` v0.1, at which point `langchain` will adopt the same versioning policy as `langchain-core`.
|
||||
|
||||
## `langchain-community`
|
||||
|
||||
`langchain-community` is currently on version `0.0.x`
|
||||
|
||||
All changes will be accompanied by a patch version increase.
|
||||
|
||||
## `langchain-experimental`
|
||||
|
||||
`langchain-experimental` is currently on version `0.0.x`
|
||||
|
||||
All changes will be accompanied by a patch version increase.
|
||||
|
||||
## Partner Packages
|
||||
|
||||
Partner packages are versioned independently.
|
||||
|
||||
# 🌟 Recognition
|
||||
|
||||
If your contribution has made its way into a release, we will want to give you credit on Twitter (only if you want though)!
|
||||
If you have a Twitter account you would like us to mention, please let us know in the PR or through another means.
|
||||
@ -0,0 +1,147 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Testing
|
||||
|
||||
All of our packages have unit tests and integration tests, and we favor unit tests over integration tests.
|
||||
|
||||
Unit tests run on every pull request, so they should be fast and reliable.
|
||||
|
||||
Integration tests run once a day, and they require more setup, so they should be reserved for confirming interface points with external services.
|
||||
|
||||
## Unit Tests
|
||||
|
||||
Unit tests cover modular logic that does not require calls to outside APIs.
|
||||
If you add new logic, please add a unit test.
|
||||
|
||||
To install dependencies for unit tests:
|
||||
|
||||
```bash
|
||||
poetry install --with test
|
||||
```
|
||||
|
||||
To run unit tests:
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
To run unit tests in Docker:
|
||||
|
||||
```bash
|
||||
make docker_tests
|
||||
```
|
||||
|
||||
To run a specific test:
|
||||
|
||||
```bash
|
||||
TEST_FILE=tests/unit_tests/test_imports.py make test
|
||||
```
|
||||
|
||||
## Integration Tests
|
||||
|
||||
Integration tests cover logic that requires making calls to outside APIs (often integration with other services).
|
||||
If you add support for a new external API, please add a new integration test.
|
||||
|
||||
**Warning:** Almost no tests should be integration tests.
|
||||
|
||||
Tests that require making network connections make it difficult for other
|
||||
developers to test the code.
|
||||
|
||||
Instead favor relying on `responses` library and/or mock.patch to mock
|
||||
requests using small fixtures.
|
||||
|
||||
To install dependencies for integration tests:
|
||||
|
||||
```bash
|
||||
poetry install --with test,test_integration
|
||||
```
|
||||
|
||||
To run integration tests:
|
||||
|
||||
```bash
|
||||
make integration_tests
|
||||
```
|
||||
|
||||
### Prepare
|
||||
|
||||
The integration tests use several search engines and databases. The tests
|
||||
aim to verify the correct behavior of the engines and databases according to
|
||||
their specifications and requirements.
|
||||
|
||||
To run some integration tests, such as tests located in
|
||||
`tests/integration_tests/vectorstores/`, you will need to install the following
|
||||
software:
|
||||
|
||||
- Docker
|
||||
- Python 3.8.1 or later
|
||||
|
||||
Any new dependencies should be added by running:
|
||||
|
||||
```bash
|
||||
# add package and install it after adding:
|
||||
poetry add tiktoken@latest --group "test_integration" && poetry install --with test_integration
|
||||
```
|
||||
|
||||
Before running any tests, you should start a specific Docker container that has all the
|
||||
necessary dependencies installed. For instance, we use the `elasticsearch.yml` container
|
||||
for `test_elasticsearch.py`:
|
||||
|
||||
```bash
|
||||
cd tests/integration_tests/vectorstores/docker-compose
|
||||
docker-compose -f elasticsearch.yml up
|
||||
```
|
||||
|
||||
For environments that requires more involving preparation, look for `*.sh`. For instance,
|
||||
`opensearch.sh` builds a required docker image and then launch opensearch.
|
||||
|
||||
|
||||
### Prepare environment variables for local testing:
|
||||
|
||||
- copy `tests/integration_tests/.env.example` to `tests/integration_tests/.env`
|
||||
- set variables in `tests/integration_tests/.env` file, e.g `OPENAI_API_KEY`
|
||||
|
||||
Additionally, it's important to note that some integration tests may require certain
|
||||
environment variables to be set, such as `OPENAI_API_KEY`. Be sure to set any required
|
||||
environment variables before running the tests to ensure they run correctly.
|
||||
|
||||
### Recording HTTP interactions with pytest-vcr
|
||||
|
||||
Some of the integration tests in this repository involve making HTTP requests to
|
||||
external services. To prevent these requests from being made every time the tests are
|
||||
run, we use pytest-vcr to record and replay HTTP interactions.
|
||||
|
||||
When running tests in a CI/CD pipeline, you may not want to modify the existing
|
||||
cassettes. You can use the --vcr-record=none command-line option to disable recording
|
||||
new cassettes. Here's an example:
|
||||
|
||||
```bash
|
||||
pytest --log-cli-level=10 tests/integration_tests/vectorstores/test_pinecone.py --vcr-record=none
|
||||
pytest tests/integration_tests/vectorstores/test_elasticsearch.py --vcr-record=none
|
||||
|
||||
```
|
||||
|
||||
### Run some tests with coverage:
|
||||
|
||||
```bash
|
||||
pytest tests/integration_tests/vectorstores/test_elasticsearch.py --cov=langchain --cov-report=html
|
||||
start "" htmlcov/index.html || open htmlcov/index.html
|
||||
|
||||
```
|
||||
|
||||
## Coverage
|
||||
|
||||
Code coverage (i.e. the amount of code that is covered by unit tests) helps identify areas of the code that are potentially more or less brittle.
|
||||
|
||||
Coverage requires the dependencies for integration tests:
|
||||
|
||||
```bash
|
||||
poetry install --with test_integration
|
||||
```
|
||||
|
||||
To get a report of current coverage, run the following:
|
||||
|
||||
```bash
|
||||
make coverage
|
||||
```
|
||||
@ -1,125 +1,3 @@
|
||||
# Langchain Tests
|
||||
|
||||
## Unit Tests
|
||||
|
||||
Unit tests cover modular logic that does not require calls to outside APIs.
|
||||
If you add new logic, please add a unit test.
|
||||
|
||||
To run unit tests:
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
To run unit tests in Docker:
|
||||
|
||||
```bash
|
||||
make docker_tests
|
||||
```
|
||||
|
||||
## Integration Tests
|
||||
|
||||
Integration tests cover logic that requires making calls to outside APIs (often integration with other services).
|
||||
If you add support for a new external API, please add a new integration test.
|
||||
|
||||
**warning** Almost no tests should be integration tests.
|
||||
|
||||
Tests that require making network connections make it difficult for other
|
||||
developers to test the code.
|
||||
|
||||
Instead favor relying on `responses` library and/or mock.patch to mock
|
||||
requests using small fixtures.
|
||||
|
||||
To install dependencies for integration tests:
|
||||
|
||||
```bash
|
||||
poetry install --with test_integration
|
||||
```
|
||||
|
||||
To run integration tests:
|
||||
|
||||
```bash
|
||||
make integration_tests
|
||||
```
|
||||
|
||||
### Prepare
|
||||
|
||||
The integration tests exercise several search engines and databases. The tests
|
||||
aim to verify the correct behavior of the engines and databases according to
|
||||
their specifications and requirements.
|
||||
|
||||
To run some integration tests, such as tests located in
|
||||
`tests/integration_tests/vectorstores/`, you will need to install the following
|
||||
software:
|
||||
|
||||
- Docker
|
||||
- Python 3.8.1 or later
|
||||
|
||||
Any new dependencies should be added by running:
|
||||
|
||||
```bash
|
||||
# add package and install it after adding:
|
||||
poetry add tiktoken@latest --group "test_integration" && poetry install --with test_integration
|
||||
```
|
||||
|
||||
Before running any tests, you should start a specific Docker container that has all the
|
||||
necessary dependencies installed. For instance, we use the `elasticsearch.yml` container
|
||||
for `test_elasticsearch.py`:
|
||||
|
||||
```bash
|
||||
cd tests/integration_tests/vectorstores/docker-compose
|
||||
docker-compose -f elasticsearch.yml up
|
||||
```
|
||||
|
||||
For environments that requires more involving preparation, look for `*.sh`. For instance,
|
||||
`opensearch.sh` builds a required docker image and then launch opensearch.
|
||||
|
||||
|
||||
### Prepare environment variables for local testing:
|
||||
|
||||
- copy `tests/integration_tests/.env.example` to `tests/integration_tests/.env`
|
||||
- set variables in `tests/integration_tests/.env` file, e.g `OPENAI_API_KEY`
|
||||
|
||||
Additionally, it's important to note that some integration tests may require certain
|
||||
environment variables to be set, such as `OPENAI_API_KEY`. Be sure to set any required
|
||||
environment variables before running the tests to ensure they run correctly.
|
||||
|
||||
### Recording HTTP interactions with pytest-vcr
|
||||
|
||||
Some of the integration tests in this repository involve making HTTP requests to
|
||||
external services. To prevent these requests from being made every time the tests are
|
||||
run, we use pytest-vcr to record and replay HTTP interactions.
|
||||
|
||||
When running tests in a CI/CD pipeline, you may not want to modify the existing
|
||||
cassettes. You can use the --vcr-record=none command-line option to disable recording
|
||||
new cassettes. Here's an example:
|
||||
|
||||
```bash
|
||||
pytest --log-cli-level=10 tests/integration_tests/vectorstores/test_pinecone.py --vcr-record=none
|
||||
pytest tests/integration_tests/vectorstores/test_elasticsearch.py --vcr-record=none
|
||||
|
||||
```
|
||||
|
||||
### Run some tests with coverage:
|
||||
|
||||
```bash
|
||||
pytest tests/integration_tests/vectorstores/test_elasticsearch.py --cov=langchain --cov-report=html
|
||||
start "" htmlcov/index.html || open htmlcov/index.html
|
||||
|
||||
```
|
||||
|
||||
## Coverage
|
||||
|
||||
Code coverage (i.e. the amount of code that is covered by unit tests) helps identify areas of the code that are potentially more or less brittle.
|
||||
|
||||
Coverage requires the dependencies for integration tests:
|
||||
|
||||
```bash
|
||||
poetry install --with test_integration
|
||||
```
|
||||
|
||||
To get a report of current coverage, run the following:
|
||||
|
||||
```bash
|
||||
make coverage
|
||||
```
|
||||
[This guide has moved to the docs](https://python.langchain.com/docs/contributing/testing)
|
||||
|
||||
Loading…
Reference in New Issue