From 9ac46cc2641b00947bb58f1d0af185bd0fb3502f Mon Sep 17 00:00:00 2001 From: Erick Friis Date: Thu, 21 Nov 2024 18:17:04 -0800 Subject: [PATCH] x --- .../how_to/integrations/community.mdx | 4 + .../how_to/integrations/from_template.mdx | 5 + .../how_to/integrations/index.mdx | 2 +- .../how_to/integrations/package.mdx | 41 ++--- .../how_to/integrations/publish.mdx | 143 ++++++++++++++++++ .../how_to/integrations/standard_tests.ipynb | 4 + .../langchain_cli/namespaces/integration.py | 8 +- 7 files changed, 174 insertions(+), 33 deletions(-) create mode 100644 docs/docs/contributing/how_to/integrations/publish.mdx diff --git a/docs/docs/contributing/how_to/integrations/community.mdx b/docs/docs/contributing/how_to/integrations/community.mdx index c7c3dadef91..945ae766f7c 100644 --- a/docs/docs/contributing/how_to/integrations/community.mdx +++ b/docs/docs/contributing/how_to/integrations/community.mdx @@ -1,3 +1,7 @@ +--- +pagination_next: null +pagination_prev: null +--- ## How to add a community integration (not recommended) :::danger diff --git a/docs/docs/contributing/how_to/integrations/from_template.mdx b/docs/docs/contributing/how_to/integrations/from_template.mdx index 22ff840ab79..9365ff23dd5 100644 --- a/docs/docs/contributing/how_to/integrations/from_template.mdx +++ b/docs/docs/contributing/how_to/integrations/from_template.mdx @@ -1,3 +1,8 @@ +--- +pagination_next: null +pagination_prev: null +--- + # How to publish an integration package from a template :::danger diff --git a/docs/docs/contributing/how_to/integrations/index.mdx b/docs/docs/contributing/how_to/integrations/index.mdx index 31d9cf2c0bf..2b2730860ec 100644 --- a/docs/docs/contributing/how_to/integrations/index.mdx +++ b/docs/docs/contributing/how_to/integrations/index.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +pagination_next: docs/contributing/how_to/integrations/package --- # Contribute Integrations diff --git a/docs/docs/contributing/how_to/integrations/package.mdx b/docs/docs/contributing/how_to/integrations/package.mdx index 09fe7f9a6f9..d9dc1211029 100644 --- a/docs/docs/contributing/how_to/integrations/package.mdx +++ b/docs/docs/contributing/how_to/integrations/package.mdx @@ -1,3 +1,7 @@ +--- +pagination_next: docs/contributing/how_to/integrations/standard_tests +pagination_prev: docs/contributing/how_to/integrations +--- # How to bootstrap a new integration package This guide walks through the process of publishing a new LangChain integration @@ -22,7 +26,10 @@ First, install Poetry: pip install poetry ``` -Next, create a new Python package with 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: ```bash poetry new langchain-parrot-link @@ -39,12 +46,12 @@ you are not using Poetry, we recommend adding these in a way that won't package 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: - +We recommended pinning these to the latest version: +Note: Replace `{latest version}` with the latest version of `langchain-tests` below. ```bash -poetry add --group test pytest langchain-tests=={latest version} +poetry add --group test pytest pytest-socket langchain-tests=={latest version} ``` You're now ready to start writing your integration package! @@ -72,7 +79,7 @@ All of these files should already exist from step 1, except for later, following the [standard tests](./standard_tests) guide. To implement `chat_models.py`, let's copy the implementation from our -[Custom Chat Model Guide](../../../how_to/custom_chat_model). +[Custom Chat Model Guide](../../../../how_to/custom_chat_model).
chat_models.py @@ -217,28 +224,6 @@ class CustomChatModelAdvanced(BaseChatModel): ```
-## Publishing your package to PyPi - -First, make sure you have a PyPi account and have logged in with Poetry: - -```bash -poetry config pypi-token.pypi -``` - -Next, build your package: - -```bash -poetry build -``` - -Finally, publish your package to PyPi: - -```bash -poetry publish -``` - -You're all set! Your package is now available on PyPi and can be installed with `pip install langchain-parrot-link`. - ## Next Steps -Now that you've published your package, you can move on to the next step: [Implement the standard tests](./standard_tests) for your integration and successfully run them. +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/publish.mdx b/docs/docs/contributing/how_to/integrations/publish.mdx new file mode 100644 index 00000000000..72812f9c151 --- /dev/null +++ b/docs/docs/contributing/how_to/integrations/publish.mdx @@ -0,0 +1,143 @@ +--- +--- + +# Publishing your package + +Now that your package is implemented and tested, you can: + +1. Publish your package to PyPi +2. Add documentation for your package to the LangChain Monorepo + +## Publishing your package to PyPi + +This guide assumes you have already implemented your package and written tests for it. If you haven't done that yet, please refer to the [implementation guide](../package) and the [testing guide](../standard_tests). + +Note that Poetry is not required to publish a package to PyPi, and we're using it in this guide end-to-end for convenience. +You are welcome to publish your package using any other method you prefer. + +First, make sure you have a PyPi account and have logged in with Poetry: + +
+ How to create a PyPi Token + +1. Go to the [PyPi website](https://pypi.org/) and create an account. +2. Go to your account settings and enable 2FA. To generate an API token, you **must** have 2FA enabled currently. +3. Go to your account settings and [generate a new API token](https://pypi.org/manage/account/token/). + +
+ +```bash +poetry config pypi-token.pypi +``` + +Next, build your package: + +```bash +poetry build +``` + +Finally, publish your package to PyPi: + +```bash +poetry publish +``` + +You're all set! Your package is now available on PyPi and can be installed with `pip install langchain-parrot-link`. + +## Adding documentation to the LangChain Monorepo + +To add documentation for your package to the LangChain Monorepo, you will need to: + +1. Fork and clone the LangChain Monorepo +2. Make a "Provider Page" at `docs/docs/integrations/providers/.ipynb` +3. Make "Component Pages" at `docs/docs/integrations//.ipynb` +4. Register your package in `libs/packages.yml` +5. Submit a PR with **only these changes** to the LangChain Monorepo + +### Fork and clone the LangChain Monorepo + +First, fork the [LangChain Monorepo](https://github.com/langchain-ai/langchain) to your GitHub account. + +Next, clone the repository to your local machine: + +```bash +git clone https://github.com//langchain.git +``` + +You're now ready to make your PR! + +### Bootstrap your documentation pages with the langchain-cli (recommended) + +To make it easier to create the necessary documentation pages, you can use the `langchain-cli` to bootstrap them for you. + +First, install the latest version of the `langchain-cli` package: + +```bash +pip install --upgrade langchain-cli +``` + +To see the available commands to bootstrap your documentation pages, run: + +```bash +langchain-cli integration create-doc --help +``` + +Let's bootstrap a provider page from the root of the monorepo: + +```bash +langchain-cli integration create-doc \ + --component-type Provider \ + --destination-dir docs/docs/integrations/providers \ + --name parrot-link \ + --name-class ParrotLink \ +``` + +And a chat model component page: + +```bash +langchain-cli integration create-doc \ + --component-type ChatModel \ + --destination-dir docs/docs/integrations/chat \ + --name parrot-link \ + --name-class ParrotLink \ +``` + +And a vector store component page: + +```bash +langchain-cli integration create-doc \ + --component-type VectorStore \ + --destination-dir docs/docs/integrations/vectorstores \ + --name parrot-link \ + --name-class ParrotLink \ +``` + +These commands will create the following 3 files, which you should fill out with information about your package: + +- `docs/docs/integrations/providers/parrot-link.ipynb` +- `docs/docs/integrations/chat/parrot-link.ipynb` +- `docs/docs/integrations/vectorstores/parrot-link.ipynb` + +### Manually create your documentation pages (if you prefer) + +If you prefer to create the documentation pages manually, you can create the same files listed +above and fill them out with information about your package. + +You can view the templates that the CLI uses to create these files [here](https://github.com/langchain-ai/langchain/tree/master/libs/cli/langchain_cli/integration_template/docs) if helpful! + +### Register your package in `libs/packages.yml` + +Finally, add your package to the `libs/packages.yml` file in the LangChain Monorepo. + +```yaml +packages: + - name: langchain-parrot-link + repo: / + path: . +``` + +For `path`, you can use `.` if your package is in the root of your repository, or specify a subdirectory (e.g. `libs/parrot-link`) if it is in a subdirectory. + +### Submit a PR with your changes + +Once you have completed these steps, you can submit a PR to the LangChain Monorepo with **only these changes**. diff --git a/docs/docs/contributing/how_to/integrations/standard_tests.ipynb b/docs/docs/contributing/how_to/integrations/standard_tests.ipynb index b5036431036..56c0a7952ae 100644 --- a/docs/docs/contributing/how_to/integrations/standard_tests.ipynb +++ b/docs/docs/contributing/how_to/integrations/standard_tests.ipynb @@ -4,6 +4,10 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "---\n", + "pagination_next: null\n", + "pagination_prev: docs/contributing/how_to/integrations/standard_tests\n", + "---\n", "# How to add standard tests to an integration\n", "\n", "When creating either a custom class for yourself or a new tool to publish in a LangChain integration, it is important to add standard tests to ensure it works as expected. This guide will show you how to add standard tests to a tool, and you can **[Skip to the test templates](#standard-test-templates-per-component)** for implementing tests for each integration.\n", diff --git a/libs/cli/langchain_cli/namespaces/integration.py b/libs/cli/langchain_cli/namespaces/integration.py index ee015c27852..e78af97c25d 100644 --- a/libs/cli/langchain_cli/namespaces/integration.py +++ b/libs/cli/langchain_cli/namespaces/integration.py @@ -140,6 +140,8 @@ TEMPLATE_MAP: dict[str, str] = { "Retriever": "retrievers.ipynb", } +_component_types_str = ", ".join(f"`{k}`" for k in TEMPLATE_MAP.keys()) + @integration_cli.command() def create_doc( @@ -170,8 +172,7 @@ def create_doc( str, typer.Option( help=( - "The type of component. Currently only 'ChatModel', " - "'DocumentLoader', 'VectorStore' supported." + f"The type of component. Currently supported: {_component_types_str}." ), ), ] = "ChatModel", @@ -220,8 +221,7 @@ def create_doc( docs_template = template_dir / TEMPLATE_MAP[component_type] else: raise ValueError( - f"Unrecognized {component_type=}. Expected one of 'ChatModel', " - f"'DocumentLoader', 'Tool'." + f"Unrecognized {component_type=}. Expected one of {_component_types_str}." ) shutil.copy(docs_template, destination_path)