Harrison/quick start (#12491)

Co-authored-by: Eugene Yurtsev <eyurtsev@gmail.com>

templates/CONTRIBUTING.md

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

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.

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.

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)

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.

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.

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

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"