Merge branch 'elastic:main' into main

Author: jonfritz

example-apps/chatbot-rag-app/.flaskenv

@@ -1,7 +1,7 @@
 frontend/build
 frontend/node_modules
 api/__pycache__
-api/.env
 .venv
 venv
-.DS_Store
+.DS_Store
+.env

example-apps/chatbot-rag-app/.gitignore

@@ -1,18 +1,16 @@
-# app/Dockerfile
-
-FROM node:16-alpine as build-step
+FROM node:22-alpine AS build-step
 WORKDIR /app
-ENV PATH /node_modules/.bin:$PATH
+ENV PATH=/node_modules/.bin:$PATH
 COPY frontend ./frontend
 RUN rm -rf /app/frontend/node_modules
 RUN cd frontend && yarn install
 RUN cd frontend && REACT_APP_API_HOST=/api yarn build
 
-FROM python:3.9-slim
+FROM python:3.12-slim
 
 WORKDIR /app
 RUN mkdir -p ./frontend/build
-COPY --from=build-step ./app/frontend/build ./frontend/build 
+COPY --from=build-step ./app/frontend/build ./frontend/build
 RUN mkdir ./api
 RUN mkdir ./data
 
@@ -24,12 +22,10 @@ RUN apt-get update && apt-get install -y \
     && rm -rf /var/lib/apt/lists/*
 
 
-COPY api ./api
-COPY data ./data
 COPY requirements.txt ./requirements.txt
 RUN pip3 install -r ./requirements.txt
-ENV FLASK_ENV production
+COPY api ./api
+COPY data ./data
 
 EXPOSE 4000
-WORKDIR /app/api
-CMD [ "python3", "-m" , "flask", "run", "--host=0.0.0.0", "--port=4000" ]
+CMD [ "python", "api/app.py"]

example-apps/chatbot-rag-app/Dockerfile

@@ -15,216 +15,164 @@ curl https://codeload.github.com/elastic/elasticsearch-labs/tar.gz/main | \
 tar -xz --strip=2 elasticsearch-labs-main/example-apps/chatbot-rag-app
 ```
 
-## Installing and connecting to Elasticsearch
-
-### Install Elasticsearch
+## Make your .env file
 
-There are a number of ways to install Elasticsearch. Cloud is best for most use-cases. Visit the [Install Elasticsearch](https://www.elastic.co/search-labs/tutorials/install-elasticsearch) for more information.
+Copy [env.example](env.example) to `.env` and fill in values noted inside.
 
-### Connect to Elasticsearch
+## Installing and connecting to Elasticsearch
 
-This app requires the following environment variables to be set to connect to Elasticsearch hosted on Elastic Cloud:
+There are a number of ways to install Elasticsearch. Cloud is best for most
+use-cases. Visit the [Install Elasticsearch](https://www.elastic.co/search-labs/tutorials/install-elasticsearch) for more information.
 
-```sh
-export ELASTIC_CLOUD_ID=...
-export ELASTIC_API_KEY=...
-```
+Once you decided your approach, edit your `.env` file accordingly.
 
-You can add these to a `.env` file for convenience. See the `env.example` file for a .env file template.
+### Running your own Elastic Stack with Docker
 
-#### Self-Hosted Elasticsearch
+If you'd like to start Elastic locally, you can use the provided
+[docker-compose-elastic.yml](docker-compose-elastic.yml) file. This starts
+Elasticsearch, Kibana, and APM Server and only requires Docker installed.
 
-You can also connect to a self-hosted Elasticsearch instance. To do so, you will need to set the following environment variables:
+Use docker compose to run Elastic stack in the background:
 
-```sh
-export ELASTICSEARCH_URL=...
+```bash
+docker compose -f docker-compose-elastic.yml up --force-recreate -d
 ```
 
-### Change the Elasticsearch index and chat_history index
-
-By default, the app will use the `workplace-app-docs` index and the chat history index will be `workplace-app-docs-chat-history`. If you want to change these, you can set the following environment variables:
-
-```sh
-ES_INDEX=workplace-app-docs
-ES_INDEX_CHAT_HISTORY=workplace-app-docs-chat-history
-```
+Then, you can view Kibana at http://localhost:5601/app/home#/
 
-## Connecting to LLM
+If asked for a username and password, use username: elastic and password: elastic.
 
-We support several LLM providers. To use one of them, you need to set the `LLM_TYPE` environment variable. For example:
+Clean up when finished, like this:
 
-```sh
-export LLM_TYPE=azure
+```bash
+docker compose -f docker-compose-elastic.yml down
 ```
 
-The following sub-sections define the configuration requirements of each supported LLM.
-
-### OpenAI
-
-To use OpenAI LLM, you will need to provide the OpenAI key via `OPENAI_API_KEY` environment variable:
+## Connecting to LLM
 
-```sh
-export LLM_TYPE=openai
-export OPENAI_API_KEY=...
-```
+We support several LLM providers, but only one is used at runtime, and selected
+by the `LLM_TYPE` entry in your `.env` file. Edit that file to choose an LLM,
+and configure its templated connection settings:
 
-You can get your OpenAI key from the [OpenAI dashboard](https://platform.openai.com/account/api-keys).
+* azure: [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
+* bedrock: [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/)
+* openai: [OpenAI Platform](https://platform.openai.com/docs/overview) and
+  services compatible with its API.
+* vertex: [Google Vertex AI](https://cloud.google.com/vertex-ai/docs)
+* mistral: [Mistral AI](https://docs.mistral.ai/)
+* cohere: [Cohere](https://docs.cohere.com/)
 
-### Azure OpenAI
+## Running the App
 
-If you want to use Azure LLM, you will need to set the following environment variables:
+There are two ways to run the app: via Docker or locally. Docker is advised for
+ease while locally is advised if you are making changes to the application.
 
-```sh
-export LLM_TYPE=azure
-export OPENAI_VERSION=... # e.g. 2023-05-15
-export OPENAI_BASE_URL=...
-export OPENAI_API_KEY=...
-export OPENAI_ENGINE=... # deployment name in Azure
-```
+### Run with docker
 
-### Bedrock LLM
+Docker compose is the easiest way, as you get one-step to:
+* build the [frontend](frontend)
+* ingest data into elasticsearch
+* run the app, which listens on http://localhost:4000
 
-To use Bedrock LLM you need to set the following environment variables in order to authenticate to AWS.
+**Double-check you have a `.env` file with all your variables set first!**
 
-```sh
-export LLM_TYPE=bedrock
-export AWS_ACCESS_KEY=...
-export AWS_SECRET_KEY=...
-export AWS_REGION=... # e.g. us-east-1
-export AWS_MODEL_ID=... # Default is anthropic.claude-v2
+```bash
+docker compose up --build --force-recreate
 ```
 
-#### AWS Config
+*Note*: First time creating the index can fail on timeout. Wait a few minutes
+and retry.
 
-Optionally, you can connect to AWS via the config file in `~/.aws/config` described here:
-https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials
+Clean up when finished, like this:
 
-```
-[default]
-aws_access_key_id=...
-aws_secret_access_key=...
-region=...
+```bash
+docker compose down
 ```
 
-### Vertex AI
+### Run locally
 
-To use Vertex AI you need to set the following environment variables. More information [here](https://python.langchain.com/docs/integrations/llms/google_vertex_ai_palm).
+If you want to run this example with Python and Node.js, you need to do a few
+things listed in the [Dockerfile](Dockerfile). The below uses the same
+production mode as used in Docker to avoid problems in debug mode.
 
-```sh
-export LLM_TYPE=vertex
-export VERTEX_PROJECT_ID=<gcp-project-id>
-export VERTEX_REGION=<gcp-region> # Default is us-central1
-export GOOGLE_APPLICATION_CREDENTIALS=<path-json-service-account>
-```
+**Double-check you have a `.env` file with all your variables set first!**
 
-### Mistral AI
+#### Build the frontend
 
-To use Mistral AI you need to set the following environment variables. The app has been tested with Mistral Large Model deployed through Microsoft Azure. More information [here](https://learn.microsoft.com/en-us/azure/ai-studio/how-to/deploy-models-mistral).
+The web assets are in the [frontend](frontend) directory, and built with yarn.
 
+```bash
+# Install and use a recent node, if you don't have one.
+nvm install --lts
+nvm use --lts
+# Build the frontend web assets
+(cd frontend; yarn install; REACT_APP_API_HOST=/api yarn build)
 ```
-export LLM_TYPE=mistral
-export MISTRAL_API_KEY=...
-export MISTRAL_API_ENDPOINT=...  # should be of the form https://<endpoint>.<region>.inference.ai.azure.com
-export MISTRAL_MODEL=...  # optional
-```
-
-### Cohere
-
-To use Cohere you need to set the following environment variables:
 
-```
-export LLM_TYPE=cohere
-export COHERE_API_KEY=...
-export COHERE_MODEL=...  # optional
-```
+#### Configure your python environment
 
-## Running the App
+Before we can run the app, we need a working Python environment with the
+correct packages installed:
 
-Once you have indexed data into the Elasticsearch index, there are two ways to run the app: via Docker or locally. Docker is advised for testing & production use. Locally is advised for development.
-
-### Through Docker
-
-Build the Docker image and run it with the following environment variables.
-
-```sh
-docker build -f Dockerfile -t chatbot-rag-app .
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+# Install dotenv which is a portable way to load environment variables.
+pip install "python-dotenv[cli]"
+pip install -r requirements.txt
 ```
 
-#### Ingest data
-
-Make sure you have a `.env` file with all your variables, then run:
+#### Run the ingest command
 
-```sh
-docker run --rm --env-file .env chatbot-rag-app flask create-index
+First, ingest the data into elasticsearch:
+```bash
+FLASK_APP=api/app.py dotenv run -- flask create-index
 ```
 
-See "Ingest data" section under Running Locally for more details about the `flask create-index` command.
-
-#### Run API and frontend
+*Note*: First time creating the index can fail on timeout. Wait a few minutes
+and retry.
 
-You will need to set the appropriate environment variables in your `.env` file. See the `env.example` file for instructions.
+#### Run the app
 
-```sh
-docker run --rm -p 4000:4000 --env-file .env -d chatbot-rag-app
+Now, run the app, which listens on http://localhost:4000
+```bash
+dotenv run -- python api/app.py
 ```
 
-Note that if you are using an LLM that requires an external credentials file (such as Vertex AI), you will need to make this file accessible to the container in the `run` command above. For this you can use a bind mount, or you can also edit the Dockerfile to copy the credentials file to the container image at build time.
-
-### Locally (for development)
-
-With the environment variables set, you can run the following commands to start the server and frontend.
-
-#### Pre-requisites
+## Advanced
 
-- Python 3.8+
-- Node 14+
+### Updating package versions
 
-#### Install the dependencies
+To update package versions, recreate [requirements.txt](requirements.txt) and
+reinstall like this. Once checked in, any commands above will use updates.
 
-For Python we recommend using a virtual environment.
-
-_ℹ️ Here's a good [primer](https://realpython.com/python-virtual-environments-a-primer) on virtual environments from Real Python._
-
-```sh
-# Create a virtual environment
-python -m venv .venv
-
-# Activate the virtual environment
+```bash
+rm -rf .venv
+python3 -m venv .venv
 source .venv/bin/activate
-
-# Install Python dependencies
+# Install dev requirements for pip-compile
+pip install pip-tools
+# Recreate requirements.txt
+pip-compile
+# Install main dependencies
 pip install -r requirements.txt
-
-# Install Node dependencies
-cd frontend && yarn && cd ..
 ```
 
-#### Ingest data
+### Elasticsearch index and chat_history index
 
-You can index the sample data from the provided .json files in the `data` folder:
+By default, the app will use the `workplace-app-docs` index and the chat
+history index will be `workplace-app-docs-chat-history`. If you want to change
+these, edit `ES_INDEX` and `ES_INDEX_CHAT_HISTORY` entries in your `.env` file.
 
-```sh
-flask create-index
-```
+### Indexing your own data
 
-By default, this will index the data into the `workplace-app-docs` index. You can change this by setting the `ES_INDEX` environment variable.
+The ingesting logic is stored in [data/index_data.py](data/index_data.py). This
+is a simple script that uses Langchain to index data into Elasticsearch, using
+`RecursiveCharacterTextSplitter` to split the large JSON documents into
+passages. Modify this script to index your own data.
 
-##### Indexing your own data
+See [Langchain documentation][loader-docs] for more ways to load documents.
 
-The ingesting logic is stored in `data/index-data.py`. This is a simple script that uses Langchain to index data into Elasticsearch, using the `JSONLoader` and `CharacterTextSplitter` to split the large documents into passages. Modify this script to index your own data.
-
-Langchain offers many different ways to index data, if you cant just load it via JSONLoader. See the [Langchain documentation](https://python.langchain.com/docs/modules/data_connection/document_loaders)
-
-Remember to keep the `ES_INDEX` environment variable set to the index you want to index into and to query from.
-
-#### Run API and frontend
-
-```sh
-# Launch API app
-flask run
-
-# In a separate terminal launch frontend app
-cd frontend && yarn start
-```
 
-You can now access the frontend at http://localhost:3000. Changes are automatically reloaded.
+---
+[loader-docs]: https://python.langchain.com/docs/how_to/#document-loaders

example-apps/chatbot-rag-app/README.md

@@ -1,9 +1,10 @@
-from flask import Flask, jsonify, request, Response
-from flask_cors import CORS
-from uuid import uuid4
-from chat import ask_question
 import os
 import sys
+from uuid import uuid4
+
+from chat import ask_question
+from flask import Flask, Response, jsonify, request
+from flask_cors import CORS
 
 app = Flask(__name__, static_folder="../frontend/build", static_url_path="/")
 CORS(app)
@@ -37,4 +38,4 @@ def create_index():
 
 
 if __name__ == "__main__":
-    app.run(port=3001, debug=True)
+    app.run(host="0.0.0.0", port=4000, debug=False)