Merge pull request #87 from cheshire-cat-ai/installation-steps

Easy install

mkdocs.yml

@@ -66,15 +66,14 @@ nav:
       - Long Term Memory: technical/basics/admin/memory.md
       - Plugins: technical/basics/admin/plugins.md
       - Settings: technical/basics/admin/settings.md
-      - Docs: technical/basics/admin/docs.md
 
   - Plugins Registry:
       - Installing a Plugin: plugins-registry/installing-plugin.md
       - Publishing a Plugin: plugins-registry/publishing-plugin.md
       - Using the Plugin Template: plugins-registry/plugin-from-template.md
 
   - Developers:
-      - API:
+      - REST API:
           - API Reference: technical/basics/cat-core.md
           - API Authentication: technical/advanced/api_auth.md
       - Plugins Reference:
@@ -97,28 +96,25 @@ nav:
       - Advanced:
           - User Management: technical/advanced/user_system.md
           - Automatic Tests: technical/advanced/tests.md
+          - Contributing: technical/advanced/contributing.md
 
   - Administrations:
       - Architecture: administrators/architecture.md
       - Environment Variables: administrators/env-variables.md
+      - Backup the Long Term Memory: technical/advanced/memory_backup.md
 
   - LLM Concepts:
       - Language Models: llm-concepts/llm.md
       - Retrieval-Augmented Generation: llm-concepts/rag.md
       - Prompt: llm-concepts/prompt.md
-      - Encoder: llm-concepts/encoder.md
+      - Embedder: llm-concepts/embedder.md
       - Vector Memory: llm-concepts/vector-memory.md
 
   - Use Cases: 
     - Cat as Main product: use-cases/main-product.md
     - Cat as Sidecar of your product: use-cases/side-car.md
     - Cat as Discord BOT: use-cases/discord-bot.md
 
-
-  - Guides:
-    - How to update the Cat Core: guides/update-the-core.md
-    - How to backup the Long Term Memory: technical/advanced/memory_backup.md
-
   - Resources:
     - Videos:
       - Installation: resources/video-installation.md

mkdocs/llm-concepts/encoder.md → mkdocs/llm-concepts/embedder.md

@@ -1,4 +1,4 @@
-# Encoder
+# Embedder (or encoder)
 
 This type of Language Model takes a string as input and returns a vector as output. This is known as an *embedding*.
 Namely, this is a condensed representation of the input content.  

mkdocs/llm-concepts/vector-memory.md

@@ -16,7 +16,7 @@ As Vector Memory the Cheshire-Cat using [Qdrant](https://qdrant.tech/), the Vect
 
 Semantic search seeks to improve search accuracy by understanding the content of the search query. The idea is to create an high-dimensional semantic space and at search time to find the nearest point (documents) to our questions.
 
-To create the vectors you must use an [encoder](https://cheshire-cat-ai.github.io/docs/llm-concepts/encoder/), the vector are stored on the vector memory, when a query is done the encoder calculates its embedding, the VectorDB calculates the cosine similaity between query and stored points and the K nearest are returned.
+To create the vectors you must use an [embedder](./embedder.md). The vectors are stored in the vector memory; when a query is done the embedder calculates its embedding, the VectorDB calculates the cosine similaity between query and stored points and the K nearest are returned.
 
 ![semantic_search](https://raw.githubusercontent.com/UKPLab/sentence-transformers/master/docs/img/SemanticSearch.png)
 

mkdocs/quickstart/installation-configuration.md

@@ -2,10 +2,10 @@
 
 ## Requirements
 
-To run the Cheshire Cat, you need to have `Docker` ([instructions](https://docs.docker.com/engine/install/)) and `docker-compose` ([instructions](https://docs.docker.com/compose/install/)) already installed on your system.
+To run the Cheshire Cat, you need to have `Docker` ([instructions](https://docs.docker.com/engine/install/)) and `docker compose` ([instructions](https://docs.docker.com/compose/install/)) already installed on your system.
 
 The Cat is not a LLM, it uses a LLM.
-Hence, when you run the Cat for the first time, you need to configure the LLM and the encoder.  
+Hence, when you run the Cat for the first time, you need to configure the LLM and the embedder.  
 Most people use [ChatGPT](https://platform.openai.com/docs/models/gpt-3-5), it's quite cheap and powerful enough.
 We will do the same during the next steps.
 
@@ -15,29 +15,45 @@ To use `ChatGPT`, you need an API key. You can request one on the provider's web
 
 ## Setup
 
-- Clone the repository on your machine
-
-```bash
-git clone https://github.com/cheshire-cat-ai/core.git cheshire-cat
+Create a folder on your machine, and inside it create a file named `compose.yml`.
+Copy/paste the following inside:
+
+```yaml
+version: '3.7'
+
+services:
+
+  cheshire-cat-core:
+    image: ghcr.io/cheshire-cat-ai/core:latest
+    container_name: cheshire_cat_core
+    ports:
+      - ${CORE_PORT:-1865}:80
+    environment:
+      - PYTHONUNBUFFERED=1
+      - WATCHFILES_FORCE_POLLING=true
+    volumes:
+      - ./static:/app/cat/static
+      - ./plugins:/app/cat/plugins
+      - ./data:/app/cat/data
 ```
 
 ## Starting the Cat
-- Enter the created folder
-
-```bash
-cd cheshire-cat
-```
     
-- Run docker containers
+- Open a terminal inside the same folder and run:
 
 ```bash
-docker-compose up
+docker compose up
 ```
 
-The first time you run the `docker-compose up` command,
-it will take several minutes to build the Docker Cat image.
+The first time you run the `docker compose up` command,
+it will take several minutes to pull the Docker Cat image.
+
+You will see three new folders:
+
+ - `data`: where long term memory and settings are stored
+ - `plugins`: where you can install and develop plugins
+ - `static`: folder to serve static files from 
 
-Once finished, the Cat will be living and running!
 
 ## First configuration of the LLM
 

mkdocs/quickstart/introduction.md

@@ -34,7 +34,7 @@ without directly modifying the core of the Cheshire Cat.
 The `Mad Hatter` is the component that manages plugins.
 
 ## Sharing Plugins
-If desired, you can publish your `Plugins` on a public registry.
+If desired, you can publish your `Plugins` on the public registry.
 Other users will be able to install them with just a single click from the Admin Portal.
 
 ## Admin Portal
@@ -49,6 +49,6 @@ In the next step, you will learn how to install the Cat, set the LLM and the bas
 We will be transforming the Cat into a sock seller.
 More in detail, we will upload some knowledge (documents) about socks knitting.
 Also, the Cat will be able to tell the price of socks according to the requested color (using a `Tool`).
-In the end, we will transform the sock seller into a poetic socks seller, changing it personality (using a `Hook`). 
+In the end, we will transform the sock seller into a poetic socks seller, changing its personality (using a `Hook`). 
 
 The example is light and fun, it should give you an idea of what is possible.

mkdocs/quickstart/stopping-the-cat.md

@@ -5,7 +5,7 @@
 When you're done using the Cat, stop the terminal by clicking on it and press `CTRL + c`. Then, run the command:
 
 ```bash
-docker-compose down
+docker compose down
 ```
 
 We want to remind you that Long-Term Memory is a locally persisted memory.

mkdocs/technical/advanced/contributing.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Thank you for considering code contribution.
+If you wanto to learn how the Cat works and join its development, there is a different installation process to follow.
+
+## Development setup
+
+- Clone the repository on your machine
+
+```bash
+git clone https://github.com/cheshire-cat-ai/core.git cheshire-cat
+```
+
+- Enter the created folder
+
+```bash
+cd cheshire-cat
+```
+
+- Run docker container
+
+```bash
+docker compose up
+```
+
+The first time you run the `docker compose up` command,
+it will take several minutes to build the Docker Cat image. Once finished, the Cat will be living and running!  
+
+To stop the Cat hit CTRL-C in the terminal, you should see the logs stopping. Then run:
+
+```bash
+docker compose down
+```
+
+## Update development setup
+
+Remember to update often both your fork and your local clone.  
+Before each session, follow these steps:
+
+- Enter the folder where you cloned the repository
+
+```bash
+cd cheshire-cat
+```
+
+- Pull updates from the GitHub repository
+
+```bash
+git pull
+```
+
+-  Build again the docker container
+
+```bash
+docker compose build --no-cache
+```
+
+-  Remove dangling images (optional)
+
+```bash
+docker rmi -f $(docker images -f "dangling=true" -q)
+```
+
+- Run docker containers
+
+```bash
+docker compose up
+```
+
+## Your First Code Contribution
+
+1. Checkout the `develop` branch (`git checkout -b develop` and then `git pull origin develop`)
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request against the `develop` branch (if it contains lots of code, please discuss it beforehand opening a issue)
+
+## Important notes
+
+- try to discuss your contribution beforehand in an issue, to make an actually useful PR
+- try to keep your PR small, single feature / fix and to the point
+- branch out from `develop` and make your PR against `develop`; branch `main` is only used for releases
+
+## Improving The Documentation
+
+Docs contribution are highly valuable for the project.
+See details on how to help with the docs [here](https://github.com/cheshire-cat-ai/docs/).
+

mkdocs/technical/advanced/tests.md

@@ -1,7 +1,7 @@
 # 🔬 Testing
 
 To run tests, start the Cat as usual.  
-Tests will run on the same containers you already launched, but with mock databases and plugin folder.
+Tests will run on the same container you already launched, but with mock databases and plugin folder.
 End to end (e2e) tests are found in `tests/routes`, while all the other folders contain unit tests and mocks / utilities.
 
 ## Run all tests

mkdocs/technical/advanced/user_system.md

@@ -5,9 +5,8 @@ The user system affects only the [working memory](../../conceptual/memory/workin
 the [episodic memory](../../conceptual/memory/long_term_memory.md).
 The other memories are shared among users.
 
-More in details, the websocket client sends the current `user_id` in the JSON message sent to the Cat.
-The Cat uses such `user_id` to [retrieve the user's working memory](https://github.com/cheshire-cat-ai/core/blob/5b84b1d600ba9e8600413ff27c033c6d8ed5d0ca/core/cat/looking_glass/cheshire_cat.py#L332)
-and to store the user's conversation [using the `user_id` as a metadatum](https://github.com/cheshire-cat-ai/core/blob/5b84b1d600ba9e8600413ff27c033c6d8ed5d0ca/core/cat/looking_glass/cheshire_cat.py#L149).
+More in details, the websocket client indicates the current `user_id` by calling the `ws://localhost:1865/ws/{user_id}` endpoint.
+The Cat uses such `user_id` to retrieve the user's working memory and to store the user's conversation (using the `user_id` as a metadatum).
 
 !!! Note
     Please, note that the user management system works only when using a custom client.