## 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[​](#-quick-start "Direct link to 🚀 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[​](#dependency-management-poetry-and-other-envdependency-managers "Direct link to Dependency Management: Poetry and other env/dependency managers")

This project utilizes [Poetry](https://python-poetry.org/) v1.7.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[​](#different-packages "Direct link to 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:

### Local Development Dependencies[​](#local-development-dependencies "Direct link to Local Development Dependencies")

Install langchain-community development requirements (for running langchain, running examples, linting, formatting, tests, and coverage):

```
poetry install --with lint,typing,test,test_integration
```

Then verify dependency installation:

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[​](#testing "Direct link to 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:

To run unit tests in Docker:

There are also [integration tests and code-coverage](https://python.langchain.com/docs/contributing/testing/) available.

### Only develop langchain\_core or langchain\_experimental[​](#only-develop-langchain_core-or-langchain_experimental "Direct link to 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:

```
cd libs/corepoetry install --with testmake test
```

Or:

```
cd libs/experimentalpoetry install --with testmake test
```

### Formatting and Linting[​](#formatting-and-linting "Direct link to Formatting and Linting")

Run these locally before submitting a PR; the CI system will check also.

#### Code Formatting[​](#code-formatting "Direct link to Code Formatting")

Formatting for this project is done via [ruff](https://docs.astral.sh/ruff/rules/).

To run formatting for docs, cookbook and templates:

To run formatting for a library, run the same command from the relevant library directory:

```
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:

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 "Direct link to 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:

To run linting for a library, run the same command from the relevant library directory:

```
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:

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[​](#spellcheck "Direct link to 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:

To fix spelling in place:

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.

```
[tool.codespell]...# Add here:ignore-words-list = 'momento,collison,ned,foor,reworkd,parth,whats,aapply,mysogyny,unsecure'
```

## Working with Optional Dependencies[​](#working-with-optional-dependencies "Direct link to 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
    
    ```
    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.
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[​](#adding-a-jupyter-notebook "Direct link to 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:

```
poetry install --with dev
```

Launch a notebook:

```
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.