diff --git a/templates/CONTRIBUTING.md b/templates/CONTRIBUTING.md deleted file mode 100644 index f7171265f3b..00000000000 --- a/templates/CONTRIBUTING.md +++ /dev/null @@ -1,18 +0,0 @@ -# Contributing - -To add a new project: - -Make sure you have `langchain-cli` installed. - -```shell -pip install -U langchain-cli -``` - -Create a new package - -```shell -langchain hub new $PROJECT_NAME -``` - -This will set up the skeleton of a package. -You can then edit the contents of the package as you desire. diff --git a/templates/README.md b/templates/README.md index 56064c73720..5f837838129 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,12 +1,9 @@ # LangServe Templates -Templates for a fully functioning app that can be hosted by LangServe. +LangServe Templates are the easiest and fastest way to build a production-ready LLM application. +These templates serve as a set of reference architectures for a wide variety of popular LLM use cases. -Some other helpful docs: - -- [Templates] - -## Usage +## Quick Start To use, first install the LangChain CLI. @@ -31,34 +28,48 @@ To pull in an existing template as a package, you first need to go into your new cd my-app ``` -And you can the add a template as a project +And you can the add a template as a project. +In this getting started guide, we will add a simple `pirate-speak` project. +All this project does is convert user input into pirate speak. ```shell -langchain serve add $PROJECT_NAME +langchain serve add pirate-speak ``` -This will pull in the specified template into `packages/$PROJECT_NAME` - -You then need to install this package so you can use it in the langserve app: - -```shell -pip install -e packages/$PROJECT_NAME -``` +This will pull in the specified template into `packages/pirate-speak` +You will then be prompted if you want to install it. +This is the equivalent of running `pip install -e packages/pirate-speak`. +You should generally accept this (or run that same command afterwards). We install it with `-e` so that if you modify the template at all (which you likely will) the changes are updated. +After that, it will ask you if you want to generate route code for this project. +This is code you need to add to your app to start using this chain. +If we accept, we will see the following code generated: + +```shell +from pirate_speak.chain import chain as pirate_speak_chain + +add_routes(app, pirate_speak_chain, path="/pirate_speak") +``` + +You can now edit the template you pulled down. +You can change the code files in `package/pirate-speak` to use a different model, different prompt, different logic. +Note that the above code snippet always expects the final chain to be importable as `from pirate_speak.chain import chain`, +so you should either keep the structure of the package similar enough to respect that or be prepared to update that code snippet. + +Once you have done as much of that as you want, it is In order to have LangServe use this project, you then need to modify `app/server.py`. -Specifically, you should add something like: +Specifically, you should add the above code snippet to `app/server.py` so that file looks like: ```python from fastapi import FastAPI from langserve import add_routes -# This depends on the structure of the package you install -from my_project import chain +from pirate_speak.chain import chain as pirate_speak_chain app = FastAPI() -add_routes(app, chain) +add_routes(app, pirate_speak_chain, path="/pirate_speak") ``` You can then spin up production-ready endpoints, along with a playground, by running: @@ -67,6 +78,39 @@ You can then spin up production-ready endpoints, along with a playground, by run langchain start ``` -## Adding a template +This now gives a fully deployed LangServe application. +For example, you get a playground out-of-the-box at [http://127.0.0.1:8000/pirate_speak/playground/](http://127.0.0.1:8000/pirate_speak/playground/): -See [here](CONTRIBUTING.md) +![playground.png](docs/playground.png) + +Access API documentation at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) + +![docs.png](docs/docs.png) + +Use the LangServe python or js SDK to interact with the API as if it were a regular [Runnable](https://python.langchain.com/docs/expression_language/). + +```python +from langserve import RemoteRunnable + +api = RemoteRunnable("http://127.0.0.1:8000/pirate_speak") +api.invoke({"text": "hi"}) +``` + +That's it for the quick start! +You have successfully downloaded your first template and deployed it with LangServe. + + +## Additional Resources + +### [Index of Templates](docs/INDEX.md) + +Explore the many templates available to use - from advanced RAG to agents. + +### [Contributing](docs/CONTRIBUTING.md) + +Want to contribute your own template? It's pretty easy! These instructions walk through how to do that. + +### [Launching LangServe from a Package](docs/LAUNCHING_PACKAGE.md) + +You can also launch LangServe from a package directly (without having to create a new project). +These instructions cover how to do that. diff --git a/templates/docs/CONTRIBUTING.md b/templates/docs/CONTRIBUTING.md new file mode 100644 index 00000000000..2d4f0d1f49e --- /dev/null +++ b/templates/docs/CONTRIBUTING.md @@ -0,0 +1,43 @@ +# Contributing + +Thanks for taking the time to contribute a new template! +We've tried to make this process as simple and painless as possible. +If you need any help at all, please reach out! + +To contribute a new template, first fork this repository. +Then clone that fork and pull it down locally. +Set up an appropriate dev environment, and make sure you are in this `template` directory. + +Make sure you have `langchain-cli` installed. + +```shell +pip install -U "langchain-cli[serve]" +``` + +You can then run the following command to create a new skeleton of a package. +By convention, package names should use `-` delimeters (not `_`). + +```shell +langchain hub new $PROJECT_NAME +``` + +You can then edit the contents of the package as you desire. +Note that by default we expect the main chain to be exposed as `chain` in the `__init__.py` file of the package. +You can change this (either the name or the location), but if you do so it is important to update the `tool.langchain` +part of `pyproject.toml`. +For example, if you update the main chain exposed to be called `agent_executor`, then that section should look like: + +```text +[tool.langserve] +export_module = "..." +export_attr = "agent_executor" +``` + +Make sure to add any requirements of the package to `pyproject.toml` (and to remove any that are not used). + +Please update the `README.md` file to give some background on your package and how to set it up. + +If you want to change the license of your template for whatever, you may! Note that by default it is MIT licensed. + +If you want to test out your package at any point in time, you can spin up a LangServe instance directly from the package. +See instructions [here](LAUNCHING_PACKAGE.md) on how to best do that. diff --git a/templates/INDEX.md b/templates/docs/INDEX.md similarity index 100% rename from templates/INDEX.md rename to templates/docs/INDEX.md diff --git a/templates/docs/LAUNCHING_PACKAGE.md b/templates/docs/LAUNCHING_PACKAGE.md new file mode 100644 index 00000000000..3ddbd6ded7d --- /dev/null +++ b/templates/docs/LAUNCHING_PACKAGE.md @@ -0,0 +1,41 @@ +# Launching LangServe from a Package + +You can also launch LangServe directly from a package, without having to pull it into a project. +This can be useful when you are developing a package and want to test it quickly. +The downside of this is that it gives you a little less control over how the LangServe APIs are configured, +which is why for proper projects we recommend creating a full project. + +In order to do this, first change your working directory to the package itself. +For example, if you are currently in this `templates` module, you can go into the `pirate-speak` package with: + +```shell +cd pirate-speak +``` + +Inside this package there is a `pyproject.toml` file. +This file contains a `tool.langchain` section that contains information on how this package should be used. +For example, in `pirate-speak` we see: + +```text +[tool.langserve] +export_module = "pirate_speak.chain" +export_attr = "chain" +``` + +This information can be used to launch a LangServe instance automatically. +In order to do this, first make sure the CLI is installed: + +```shell +pip install -U "langchain-cli[serve]" +``` + +You can then run: + +```shell +langchain hub start +``` + +This will spin up endpoints, documentation, and playground for this chain. +For example, you can access the playground at [http://127.0.0.1:8000/playground/](http://127.0.0.1:8000/playground/) + +![playground.png](playground.png) diff --git a/templates/docs/docs.png b/templates/docs/docs.png new file mode 100644 index 00000000000..82f49ba6d9b Binary files /dev/null and b/templates/docs/docs.png differ diff --git a/templates/docs/playground.png b/templates/docs/playground.png new file mode 100644 index 00000000000..6ecc38a40b8 Binary files /dev/null and b/templates/docs/playground.png differ diff --git a/templates/pirate-speak/LICENSE b/templates/pirate-speak/LICENSE new file mode 100644 index 00000000000..426b6509034 --- /dev/null +++ b/templates/pirate-speak/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 LangChain, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/templates/pirate-speak/README.md b/templates/pirate-speak/README.md new file mode 100644 index 00000000000..953e089af65 --- /dev/null +++ b/templates/pirate-speak/README.md @@ -0,0 +1,9 @@ +# pirate-speak + +This simple application converts user input into pirate speak + +## LLM + +This template will use `OpenAI` by default. + +Be sure that `OPENAI_API_KEY` is set in your environment. diff --git a/templates/pirate-speak/pirate_speak/__init__.py b/templates/pirate-speak/pirate_speak/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/templates/pirate-speak/pirate_speak/chain.py b/templates/pirate-speak/pirate_speak/chain.py new file mode 100644 index 00000000000..38777dee722 --- /dev/null +++ b/templates/pirate-speak/pirate_speak/chain.py @@ -0,0 +1,17 @@ +from langchain.chat_models import ChatOpenAI +from langchain.prompts import ChatPromptTemplate + +_prompt = ChatPromptTemplate.from_messages( + [ + ( + "system", + "Translate user input into pirate speak", + ), + ("human", "{text}"), + ] +) +_model = ChatOpenAI() + +# if you update this, you MUST also update ../pyproject.toml +# with the new `tool.langserve.export_attr` +chain = _prompt | _model diff --git a/templates/pirate-speak/pyproject.toml b/templates/pirate-speak/pyproject.toml new file mode 100644 index 00000000000..19c88547bb2 --- /dev/null +++ b/templates/pirate-speak/pyproject.toml @@ -0,0 +1,24 @@ +[tool.poetry] +name = "pirate_speak" +version = "0.0.1" +description = "" +authors = [] +readme = "README.md" + +[tool.poetry.dependencies] +python = ">=3.8.1,<4.0" +langchain = ">=0.0.313, <0.1" +openai = "^0.28.1" + +[tool.poetry.group.dev.dependencies] +langchain-cli = ">=0.0.4" +fastapi = "^0.104.0" +sse-starlette = "^1.6.5" + +[tool.langserve] +export_module = "pirate_speak.chain" +export_attr = "chain" + +[build-system] +requires = ["poetry-core"] +build-backend = "poetry.core.masonry.api" diff --git a/templates/pirate-speak/tests/__init__.py b/templates/pirate-speak/tests/__init__.py new file mode 100644 index 00000000000..e69de29bb2d