-
-
).
- - If you use Gradio for development, check out our theme here: [kotaemon-gradio-theme](https://github.com/lone17/kotaemon-gradio-theme).
+.
+- **Gradio Theme**: If you use Gradio for development, check out our theme here: [kotaemon-gradio-theme](https://github.com/lone17/kotaemon-gradio-theme).
## Key Features
-- **Host your own document QA (RAG) web-UI**. Support multi-user login, organize your files in private / public collections, collaborate and share your favorite chat with others.
+- **Host your own document QA (RAG) web-UI**: Support multi-user login, organize your files in private/public collections, collaborate and share your favorite chat with others.
-- **Organize your LLM & Embedding models**. Support both local LLMs & popular API providers (OpenAI, Azure, Ollama, Groq).
+- **Organize your LLM & Embedding models**: Support both local LLMs & popular API providers (OpenAI, Azure, Ollama, Groq).
-- **Hybrid RAG pipeline**. Sane default RAG pipeline with hybrid (full-text & vector) retriever + re-ranking to ensure best retrieval quality.
+- **Hybrid RAG pipeline**: Sane default RAG pipeline with hybrid (full-text & vector) retriever and re-ranking to ensure best retrieval quality.
-- **Multi-modal QA support**. Perform Question Answering on multiple documents with figures & tables support. Support multi-modal document parsing (selectable options on UI).
+- **Multi-modal QA support**: Perform Question Answering on multiple documents with figures and tables support. Support multi-modal document parsing (selectable options on UI).
-- **Advance citations with document preview**. By default the system will provide detailed citations to ensure the correctness of LLM answers. View your citations (incl. relevant score) directly in the _in-browser PDF viewer_ with highlights. Warning when retrieval pipeline return low relevant articles.
+- **Advanced citations with document preview**: By default the system will provide detailed citations to ensure the correctness of LLM answers. View your citations (incl. relevant score) directly in the _in-browser PDF viewer_ with highlights. Warning when retrieval pipeline return low relevant articles.
-- **Support complex reasoning methods**. Use question decomposition to answer your complex / multi-hop question. Support agent-based reasoning with ReAct, ReWOO and other agents.
+- **Support complex reasoning methods**: Use question decomposition to answer your complex/multi-hop question. Support agent-based reasoning with `ReAct`, `ReWOO` and other agents.
-- **Configurable settings UI**. You can adjust most important aspects of retrieval & generation process on the UI (incl. prompts).
+- **Configurable settings UI**: You can adjust most important aspects of retrieval & generation process on the UI (incl. prompts).
-- **Extensible**. Being built on Gradio, you are free to customize / add any UI elements as you like. Also, we aim to support multiple strategies for document indexing & retrieval. `GraphRAG` indexing pipeline is provided as an example.
+- **Extensible**: Being built on Gradio, you are free to customize or add any UI elements as you like. Also, we aim to support multiple strategies for document indexing & retrieval. `GraphRAG` indexing pipeline is provided as an example.
## Installation
-### For end users
+> If you are not a developer and just want to use the app, please check out our easy-to-follow [User Guide](https://cinnamon.github.io/kotaemon/). Download the `.zip` file from the [latest release](https://github.com/Cinnamon/kotaemon/releases/latest) to get all the newest features and bug fixes.
-This document is intended for developers. If you just want to install and use the app as
-it is, please follow the non-technical [User Guide](https://cinnamon.github.io/kotaemon/).
-Use the most recent release `.zip` to include latest features and bug-fixes.
+### System requirements
-### For developers
+1. [Python](https://www.python.org/downloads/) >= 3.10
+2. [Docker](https://www.docker.com/): optional, if you [install with Docker](#with-docker-recommended)
+3. [Unstructured](https://docs.unstructured.io/open-source/installation/full-installation#full-installation) if you want to process files other than `.pdf`, `.html`, `.mhtml`, and `.xlsx` documents. Installation steps differ depending on your operating system. Please visit the link and follow the specific instructions provided there.
-#### System requirements
+### With Docker (recommended)
-1. Python >=3.10
-2. (optional) [Docker](https://www.docker.com/)
+1. We support both `lite` & `full` version of Docker images. With `full`, the extra packages of `unstructured` will be installed as well, it can support additional file types (`.doc`, `.docx`, ...) but the cost is larger docker image size. For most users, the `lite` image should work well in most cases.
-##### If you would like to process files other than .pdf, .html, .mhtml, and .xlsx documents
+ - To use the `lite` version.
-You will need to install the system dependencies of [unstructured](https://docs.unstructured.io/open-source/installation/full-installation#full-installation). The installations vary by operating system, so please go to the link and follow the instructions there.
+ ```bash
+ docker run \
+ -e GRADIO_SERVER_NAME=0.0.0.0 \
+ -e GRADIO_SERVER_PORT=7860 \
+ -p 7860:7860 -it --rm \
+ ghcr.io/cinnamon/kotaemon:main-lite
+ ```
-#### With Docker (recommended)
+ - To use the `full` version.
-We support both `lite` & `full` version of Docker images. With `full`, the extra packages of `unstructured` will be installed as
-well, it can support additional file types (.doc, .docx, ...) but the cost is larger docker image size. For most users, the `lite` image should work well in most cases.
+ ```bash
+ docker run \
+ -e GRADIO_SERVER_NAME=0.0.0.0 \
+ -e GRADIO_SERVER_PORT=7860 \
+ -p 7860:7860 -it --rm \
+ ghcr.io/cinnamon/kotaemon:main-full
+ ```
-- To use the `lite` version.
+2. We currently support and test two platforms: `linux/amd64` and `linux/arm64` (for newer Mac). You can specify the platform by passing `--platform` in the `docker run` command. For example:
-```
-docker run \
--e GRADIO_SERVER_NAME=0.0.0.0 \
--e GRADIO_SERVER_PORT=7860 \
--p 7860:7860 -it --rm \
-ghcr.io/cinnamon/kotaemon:main-lite
-```
+ ```bash
+ # To run docker with platform linux/arm64
+ docker run \
+ -e GRADIO_SERVER_NAME=0.0.0.0 \
+ -e GRADIO_SERVER_PORT=7860 \
+ -p 7860:7860 -it --rm \
+ --platform linux/arm64 \
+ ghcr.io/cinnamon/kotaemon:main-lite
+ ```
-- To use the `full` version.
+3. Once everything is set up correctly, you can go to `http://localhost:7860/` to access the WebUI.
-```
-docker run \
--e GRADIO_SERVER_NAME=0.0.0.0 \
--e GRADIO_SERVER_PORT=7860 \
--p 7860:7860 -it --rm \
-ghcr.io/cinnamon/kotaemon:main-full
-```
+4. We use [GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) to store docker images, all images can be found [here.](https://github.com/Cinnamon/kotaemon/pkgs/container/kotaemon)
-Currently, two platforms: `linux/amd64` and `linux/arm64` (for newer Mac) are provided & tested. User can specify the platform by passing `--platform` in the docker run command. For example:
+### Without Docker
-```
-# To run docker with platform linux/arm64
-docker run \
--e GRADIO_SERVER_NAME=0.0.0.0 \
--e GRADIO_SERVER_PORT=7860 \
--p 7860:7860 -it --rm \
---platform linux/arm64 \
-ghcr.io/cinnamon/kotaemon:main-lite
-```
+1. Clone and install required packages on a fresh python environment.
-If everything is set up fine, navigate to `http://localhost:7860/` to access the web UI.
+ ```shell
+ # optional (setup env)
+ conda create -n kotaemon python=3.10
+ conda activate kotaemon
-We use [GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) to store docker images, all images can be found [here.](https://github.com/Cinnamon/kotaemon/pkgs/container/kotaemon)
+ # clone this repo
+ git clone https://github.com/Cinnamon/kotaemon
+ cd kotaemon
-#### Without Docker
+ pip install -e "libs/kotaemon[all]"
+ pip install -e "libs/ktem"
+ ```
-- Clone and install required packages on a fresh python environment.
+2. Create a `.env` file in the root of this project. Use `.env.example` as a template
-```shell
-# optional (setup env)
-conda create -n kotaemon python=3.10
-conda activate kotaemon
+ The `.env` file is there to serve use cases where users want to pre-config the models before starting up the app (e.g. deploy the app on HF hub). The file will only be used to populate the db once upon the first run, it will no longer be used in consequent runs.
-# clone this repo
-git clone https://github.com/Cinnamon/kotaemon
-cd kotaemon
-
-pip install -e "libs/kotaemon[all]"
-pip install -e "libs/ktem"
-
-```
-
-- Create a .env file in the root of this project. Use .env.example as a template
-
-The .env file is there to serve use cases where users want to pre-config the models before starting up the app (e.g. deploy the app on HF hub). The file will only be used to populate the db once upon the first run, it will no longer be used in consequent runs.
-
-- (Optional) To enable in-browser PDF_JS viewer, download [PDF_JS_DIST](https://github.com/mozilla/pdf.js/releases/download/v4.0.379/pdfjs-4.0.379-dist.zip) and extract it to `libs/ktem/ktem/assets/prebuilt`
+3. (Optional) To enable in-browser `PDF_JS` viewer, download [PDF_JS_DIST](https://github.com/mozilla/pdf.js/releases/download/v4.0.379/pdfjs-4.0.379-dist.zip) then extract it to `libs/ktem/ktem/assets/prebuilt`
-- Start the web server:
+4. Start the web server:
-```shell
-python app.py
-```
+ ```shell
+ python app.py
+ ```
-The app will be automatically launched in your browser.
+ - The app will be automatically launched in your browser.
+ - Default username and password are both `admin`. You can set up additional users directly through the UI.
-Default username / password are: `admin` / `admin`. You can setup additional users directly on the UI.
+ 
-
+5. Check the `Resources` tab and `LLMs and Embeddings` and ensure that your `api_key` value is set correctly from your `.env` file. If it is not set, you can set it there.
-- Check the Resources tab and LLMs and Embeddings and ensure that your `api_key` value is set correctly from your `.env`. file. If it is not set, you can set it here.
-
-## Setup GraphRAG
+### Setup GraphRAG
> [!NOTE]
> Currently GraphRAG feature only works with OpenAI or Ollama API.
-- [*If you are not using Docker installation*], install GraphRAG with `pip install graphrag future`
-- To use GraphRAG retriever feature, make sure to set `GRAPHRAG_API_KEY` environment variables (or in the `.env` file).
-- To use GraphRAG with local models (Ollama), or setup custom default LLM / other configurations, set `USE_CUSTOMIZED_GRAPHRAG_SETTING=true` and tweak your GraphRAG settings in `settings.yaml.example`.
+- **Non-Docker Installation**: If you are not using Docker, install GraphRAG with the following command:
-## Setup local models (for local / private RAG)
+ ```shell
+ pip install graphrag future
+ ```
+
+- **Setting Up API KEY**: To use the GraphRAG retriever feature, ensure you set the `GRAPHRAG_API_KEY` environment variable. You can do this directly in your environment or by adding it to a `.env` file.
+- **Using Local Models and Custom Settings**: If you want to use GraphRAG with local models (like `Ollama`) or customize the default LLM and other configurations, set the `USE_CUSTOMIZED_GRAPHRAG_SETTING` environment variable to true. Then, adjust your settings in the `settings.yaml.example` file.
+
+### Setup Local Models (for local/private RAG)
See [Local model setup](docs/local_model.md).
-## Customize your application
+### Customize your application
-By default, all application data are stored in `./ktem_app_data` folder. You can backup or copy this folder to move your installation to a new machine.
+- By default, all application data is stored in the `./ktem_app_data` folder. You can back up or copy this folder to transfer your installation to a new machine.
-For advance users or specific use-cases, you can customize those files:
+- For advanced users or specific use cases, you can customize these files:
-- `flowsettings.py`
-- `.env`
+ - `flowsettings.py`
+ - `.env`
-### `flowsettings.py`
+#### `flowsettings.py`
This file contains the configuration of your application. You can use the example
-[here](flowsettings.py) as the
-starting point.
+[here](flowsettings.py) as the starting point.