Add docs regarding vscode debugger, c# client, FAQ, Architecture and …

…forms (cheshire-cat-ai#146) * Vscode Debugger Document * C# client page * Documentations regarding FAQ, Architecture and forms * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/administrators/architecture.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/faq.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * Update mkdocs/technical/debugging/vscode.md Co-authored-by: Adelina <[email protected]> * English fixes * Validators link --------- Co-authored-by: Adelina <[email protected]>
sambarza · May 7, 2024 · 5fd1a09 · 5fd1a09
1 parent 638026b
commit 5fd1a09
Show file tree

Hide file tree

Showing 12 changed files with 439 additions and 37 deletions.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -46,15 +46,16 @@ nav:
     - Plugin: technical/plugins/plugins.md
     - Tools: technical/plugins/tools.md
     - Hooks: technical/plugins/hooks.md
+    - Forms: technical/plugins/forms.md
     - Logging: technical/plugins/logging.md
     - Settings: technical/plugins/settings.md
     - Dependencies: technical/plugins/dependencies.md
     - Python Reference: technical/API_Documentation/
     - Registry:
       - Using the Plugin Template: plugins-registry/plugin-from-template.md
       - Publishing a Plugin: plugins-registry/publishing-plugin.md
-    # - Debugging:
-    #     - Visual Studio Code: technical/debugging/vscode.md
+    - Debugging:
+        - Visual Studio Code: technical/debugging/vscode.md
 
   - Framework:
       - LLM Concepts:
@@ -93,6 +94,7 @@ nav:
         - TypeScript: technical/clientlib/clientlib-typescript.md
         - PHP: technical/clientlib/clientlib-php.md
         - Ruby: technical/clientlib/clientlib-ruby.md
+        - C#: technical/clientlib/clientlib-csharp.md
     - Administrations:
         - Architecture: administrators/architecture.md
         - Environment Variables: administrators/env-variables.md
@@ -185,4 +187,4 @@ markdown_extensions:
       custom_fences:
         - name: mermaid
           class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
+          format: !!python/name:pymdownx.superfences.fence_code_format
diff --git a/mkdocs/administrators/architecture.md b/mkdocs/administrators/architecture.md
@@ -1,27 +1,122 @@
 # Architecture
 
-The Cheshire Cat framework consists of four components: the Core, the Vector Database, the LLM and the Admin Portal.
+The Cheshire Cat framework consists of four components: **the Core**, **the Vector Database**, **the LLM** and **the embedder**.
 
-The Core and the Admin Portal are implemented within the framework, while the Vector Database and the LLM are external dependencies. 
+The Core and the Admin Portal are implemented within the framework, while the Vector Database, the LLM and the embedder are external dependencies.
 
-The Core communicates with both the Vector Database and the LLM, while The Admin Portal communicates with the Core.
+The Core communicates with the Vector Database, the LLM and the embedder, while The Admin Portal communicates with the Core.
 
-The Core is implemented in Python, Qdrant is utilized as Vector Database, the Core support different LLMs (see the [complete list](#compatible-llms) below), the Admin Portal is implemented using the Vue framework.
+The Core is implemented in Python, Qdrant is utilized as Vector Database, the Core support different LLMs and Embbeders (see the [complete list](#compatible-models) below), the Admin Portal is implemented using the Vue framework.
 
-## Docker Compose Images
-To facilitate, speed up, and standardize the Cat's user experience, the Cat  contains configuration for use inside Docker.
+# Core
 
-When executing `docker compose build` two Docker images are generated. The first one contains the Cat Core and Admin Portal, while the second one contains the Vector Database. The container name of the core is `cheshire_cat_core` and the name of the Vector Database image is `cheshire_vector_memory`.
+## Docker Images
 
-The local Cat core path `./core` is mounted to the image `cheshire_cat_core`, by default changes to files in this folder force a restart of the Core, this behavior can be disable using the [`DEBUG`](env-variables.md/#debug) environment variables.
+To facilitate, speed up, and standardize the Cat's user experience, the Cat contains configuration for use inside Docker.
 
-As default the Admin Portal connect to the core using `localhost` and port `1678`, these values can be customized using [environment variables](env-variables.md#core_host). This port is the only one exposed by the `cheshire_cat_core` image.
+You can use the pre-compiled images present in the Repo's Docker Registry or build it from scratch:
+
+1. To use the pre-compiled image, add `ghcr.io/cheshire-cat-ai/core:<tag-version>` as value of `image` under the name of the service in the docker-compose:
+
+    ```yml
+    cheshire-cat-core:
+        image: ghcr.io/cheshire-cat-ai/core:1.5.1
+    ```
+
+2. To build it from scratch execute `docker compose build` in the repo folder just cloned.
+
+    This will generate two Docker images. The first one contains the Cat Core and Admin Portal.
+    The container name of the core is `cheshire_cat_core`.
+
+The Cat core path `./core` is mounted into the image `cheshire_cat_core`, by default changes to files in this folder force a restart of the Core, this behavior can be disabled using the [`DEBUG`](env-variables.md/#debug) environment variable.
+
+## Admin Portal
+
+The Admin Portal connects to the core using `localhost` through the port exposed when the container was created, this value can be customized using [environment variables](env-variables.md#core_host). This port is the only one exposed by the `cheshire_cat_core` image.
 
 ## Logging
+
 All the log messages are printed on the standard output and log level can be configured with [`LOG_LEVEL`](env-variables.md#log_level) environment variables. You can check logging system documentation [here](../technical/plugins/logging.md).
 
 ## Configuration
+
 Some options of the Core can be customized using [environment variables](env-variables.md).
 
-## Compatible LLMs
-TODO
+## Compatible Models
+
+The cat is agnostic, meaning You can attach your preferred llm and embedder model/provider. The Cat supports the most used ones, but you can increase the number of models/providers by [plugins](/technical/plugins/hooks/#__tabbed_1_5), here is a list of the main ones:
+
+1. OpenAI and Azure OpenAI
+2. Cohere
+3. Ollama (LLM model only)
+4. HuggingFace TextInference API (LLM model only)
+5. Google Gemini
+6. Qdrant FastEmbed (Embedder model only)
+
+# Vector Memory
+
+## What we use as vector memory?
+
+The Cat provides a connection to [qdrant](https://qdrant.tech/) through his Python client.
+By default the Core tries to connect to a Qdrant database, if the connection fails then it switches to the `local Qdrant database`.
+It is highly recommended to connect the Cat to a **Qdrant database** to increase performance and capacity!
+
+## Qdrant Cloud or Self Hosting
+
+**Qdrant** provides to 2 paths:
+
+1. Self-host Qdrant by using docker, follows an example docker-compose:
+
+   ```yml
+   version: '3.7'
+
+    services:
+    cheshire-cat-core:
+        image: ghcr.io/cheshire-cat-ai/core:1.5.1
+        container_name: cheshire_cat_core
+        depends_on:
+            - cheshire-cat-vector-memory
+        environment:
+            - PYTHONUNBUFFERED=1
+            - WATCHFILES_FORCE_POLLING=true
+            - CORE_HOST=${CORE_HOST:-localhost}
+            - CORE_PORT=${CORE_PORT:-1865}
+            - QDRANT_HOST=${QDRANT_HOST:-cheshire_cat_vector_memory}
+            - QDRANT_PORT=${QDRANT_PORT:-6333}
+            - CORE_USE_SECURE_PROTOCOLS=${CORE_USE_SECURE_PROTOCOLS:-}
+            - API_KEY=${API_KEY:-}
+            - LOG_LEVEL=${LOG_LEVEL:-WARNING}
+            - DEBUG=${DEBUG:-true}
+            - SAVE_MEMORY_SNAPSHOTS=${SAVE_MEMORY_SNAPSHOTS:-false}
+        ports:
+            - ${CORE_PORT:-1865}:80
+        volumes:
+            - ./cat/static:/app/cat/static
+            - ./cat/plugins:/app/cat/plugins
+            - ./cat/data:/app/cat/data
+        restart: unless-stopped
+
+    cheshire-cat-vector-memory:
+        image: qdrant/qdrant:v1.7.1
+        container_name: cheshire_cat_vector_memory
+        expose:
+            - 6333
+        volumes:
+            - ./cat/long_term_memory/vector:/qdrant/storage
+        restart: unless-stopped
+   ```
+
+2. Use Qdrant Cloud, by setting `QDRANT_HOST`, `QDRANT_PORT` and `QDRANT_API_KEY` Enviroment Variables. Follows an example of `.env` file:
+
+    ```bash
+        # Qdrant server
+        QDRANT_HOST=<url of the cluster>
+        QDRANT_PORT=<port of the cluster, usually 6333>
+        QDRANT_API_KEY=<api-key>
+    ```
+
+# Admin Portal
+
+## Use case
+
+The Admin Portal is an administration/debugging panel to interact with the Cat by chatting, uploading files, exploring the memory, changing the LLM and Embedder Models while providing minimal authentication through an `api_key`.
diff --git a/mkdocs/assets/img/technical/forms/how_invalid_is_display.png b/mkdocs/assets/img/technical/forms/how_invalid_is_display.png
diff --git a/mkdocs/assets/img/technical/forms/how_is_confirm_display.png b/mkdocs/assets/img/technical/forms/how_is_confirm_display.png
diff --git a/mkdocs/assets/img/technical/forms/how_is_display.png b/mkdocs/assets/img/technical/forms/how_is_display.png
diff --git a/mkdocs/assets/img/vscode-debugger/image.png b/mkdocs/assets/img/vscode-debugger/image.png
diff --git a/mkdocs/assets/img/vscode-debugger/run_debugger.png b/mkdocs/assets/img/vscode-debugger/run_debugger.png
diff --git a/mkdocs/faq.md b/mkdocs/faq.md
@@ -23,6 +23,19 @@ We plan to adopt local LLMs, at which point all your data will be under your con
 
 On the other hand, [Langchain](https://github.com/langchain-ai/langchain) is a framework for developing applications powered by language models. It offers tons of composable tools and integrations to this purpose and the Cheshire Cat makes use of some of them to manage chains, agents, llm/embedder. You can take an in depth look at our [core](https://github.com/cheshire-cat-ai/core) if you are purr-ious about it.
 
+#### I want to use the admin page for...
+
+The admin panel is meant to be an administration interface. It's purpose is to chat with the Cat only to debug/play with it, it is not intended to be a final widget chat used by eventual final users.
+
+We provide a [widget](https://github.com/cheshire-cat-ai/widget-vue) to connect the Cat to your product.
+
+You are free to modify the Admin to adapt it to your product, **however** you will need to respect the GPL3 Licence, meaning you are free to fork the codebase and go on your own, but you are forced to open source eventual changes.
+
+#### Why the Admin does not provide Basic (username/password) or Third-party Authentication (such as OAuth)?
+
+The only use case of the Admin is to provide a more friendly way to interact with the Cat with **basic** authentication through an  `api_key`.
+
+
 ## Basic Info
 
 #### Can I insert a long article into the chat?
@@ -53,28 +66,9 @@ You can delete the `long_term_memory` folder and restart the Cat!
 
 Please check if you have a valid credit card connected or if you have used up all the credits of your OpenAI trial period.
 
-#### Everything works in localhost but not on another server
-
-You should configure ports in the `.env` file. Change according to your preferred host and ports:
-
-```text
-# Decide host and port for your Cat. Default will be localhost:1865
-CORE_HOST=anotherhost.com
-CORE_PORT=9000
-```
-
-#### Why the admin panel is asking for an auth key?
-You are probably accessing the admin from outside (maybe you host the cat in a server, or you are accessing the admin in your phone).
-Change according to your machine ip address and ports:
-```env
-# Decide host and port for your Cat. Default will be localhost:1865
-CORE_HOST=anotherhost.com 
-CORE_PORT=9000
-```
-
 #### Docker has no permissions to write
 
-This is a matter with your docker installation or the user you run docker from.
+This is a matter with your docker installation or the user you run docker from. Usually you can resolve it by using **sudo** command before calling any docker command, but it's better to create a `docker` group on your Linux system and give [root-level privileges](https://docs.docker.com/engine/install/linux-postinstall/) to docker.
 
 #### The Cat seems not to be working from inside a Virtual Machine
 
@@ -103,6 +97,9 @@ CORE_HOST=localhost
 CORE_PORT=9000
 ```
 
+#### Can I use a different vector database than Qdrant?
+At the moment, we don't provide any way to switch the vector database 😿 but it is planned for the future.
+
 ## Security
 
 #### Where is the OpenAI API key (or other keys) saved in the Cat?

diff --git a/mkdocs/plugins-registry/installing-plugin.md b/mkdocs/plugins-registry/installing-plugin.md
@@ -10,7 +10,6 @@ Installing plugins from our registry is a seamless process that enhances your Ch
 4. **Installation**: Once you've found the plugin, click the "Install" button.
 5. **Wait for Completion**: The admin will show a loading spinner until the plugin installation is not completed.
 
-
 ![Admin plugin install from registry](../assets/img/admin_screenshots/install-plugin-from-registry.gif)
 
 ## Manual Installation
@@ -28,4 +27,4 @@ Manual installation grants users more control over the process and facilitates t
 After installing a plugin, consider these steps:
 
 - **Refresh**: The admin refreshes automatically after the installation but if for some reason the plugin does not show, refresh the page or check cat logs for any errors;
-- **Settings Configuration**: If the newly installed plugin requires setup or configuration, look for the cog icon associated with the plugin. Click on it to access and adjust the plugin's settings according to your preferences.
+- **Settings Configuration**: If the newly installed plugin requires setup or configuration, look for the cog icon associated with the plugin. Click on it to access and adjust the plugin's settings according to your preferences.
diff --git a/mkdocs/technical/clientlib/clientlib-csharp.md b/mkdocs/technical/clientlib/clientlib-csharp.md
@@ -0,0 +1,6 @@
+# &#128640; Client Library C\#
+
+The Cheshire Cat provides a C# API client that allows you to chat with the Cat (using WebSocket) and provides APIs to interact with all the control plane endpoints.
+
+The package is public released on Github:
+[Cheshire Cat C# API Client](https://github.com/cheshire-cat-ai/api-client-csharp){:target="_blank"}
diff --git a/mkdocs/technical/debugging/vscode.md b/mkdocs/technical/debugging/vscode.md
@@ -1,3 +1,122 @@
 # &#128640; Debug with Visual Studio Code
 
-The Plugin `Debug Server for VSCode` help you for debug with Visual Studio Code, install it from the [public plugins registry](../../plugins-registry/installing-plugin.md) and then follow the [instructions](https://github.com/sambarza/cc-vscode-debugpy){:target="_blank"}
+The `Debug Server for VSCode` plugin helps you to debug the Cat with Visual Studio Code, install it from the [public plugins registry](../../plugins-registry/installing-plugin.md) or [download the zip file](https://github.com/sambarza/cc-vscode-debugpy) (and follow the [Manual Instruction](../../plugins-registry/installing-plugin.md/#manual-installation)).
+
+## Add a new port to the container
+
+After the installation, you will need to expose a new port to the container:
+
+1. If you run the cat with `docker-compose`, expose the port by adding the following line under `ports` section:
+
+    ```yml
+        ports:
+            - ${CORE_PORT:-1865}:80
+            - 5678:5678           < --- add this line
+    ```
+
+2. If you run the cat with `docker run`, expose the port by using the `-p <host>:<container>` argument in the command like so:
+
+    ```bash
+        docker run --rm -it \ 
+        -v ./data:/app/cat/data \ 
+        -v ./plugins:/app/cat/plugins \ 
+        -p 1865:80 \ 
+        -p 5678:5678 \  < --- add this line
+        ghcr.io/cheshire-cat-ai/core:latest
+    ```
+
+## Configure vscode
+
+Once you have exposed the port, you will need to create a `launch.json` file having two different options:
+
+   1. Use the `Run and Debug` tab to create it, selecting `Python Debugger` and then `Remote Attach` (Follow the prompts by answering with the default proposed).
+   2. Create a folder in the root directory called `.vscode` and add the `launch.json` file into it.
+
+            ├── <name of the root directory>
+            │   ├── core
+            │   ├── .vscode
+            │   │   ├──launch.json
+
+After the creation of the launch.json, Copy-Paste this config:
+
+1. If you run using `docker-compose`:
+
+    ```json
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Python: Remote Attach to Cat",
+                "type": "python",
+                "request": "attach",
+                "connect": {
+                    "host": "localhost",
+                    "port": 5678
+                },
+                "pathMappings": [
+                    {
+                        "localRoot": "${workspaceFolder}/core",
+                        "remoteRoot": "/app"
+                    }
+                ],
+                "justMyCode": true
+            }
+        ]
+    }
+    ```
+
+2. If you run using `docker run`:
+
+    ```json
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Python: Remote Attach to Cat",
+                "type": "python",
+                "request": "attach",
+                "connect": {
+                    "host": "localhost",
+                    "port": 5678
+                },
+                "pathMappings": [
+                    {
+                        "localRoot": "${workspaceFolder}/",
+                        "remoteRoot": "/app/cat"
+                    }
+                ],
+                "justMyCode": true
+            }
+        ]  
+    }
+    ```
+
+## Connect vscode to the cat
+
+To Connect the vscode debugger, ask the cat to help you on debugging ![ask help to debug](../../assets/img/vscode-debugger/image.png) and in the `Run and Debug` tab start the debugging by clicking the `Play button` ▶️ or Use the shortcut `F5`.
+
+![Enable The debugger](../../assets/img/vscode-debugger/run_debugger.png)
+
+You are ready to debug your plugin!
+
+If you are new in VS code debugging, check the [official docs](https://code.visualstudio.com/Docs/editor/debugging).
+
+## Troubleshooting
+
+#### I click the button but then I don't see the debugging bar / the breakpoints are not respected
+
+This usually means that the debugger is not active, make sure to activate the debugger by asking the Cat.
+
+#### I cannot explore the code outside of my plugin
+
+By default, you can only explore your "own" code but you can disable this by setting the param `justMyCode` to false in the `launch.json` file.
+
+#### My Cat is installed in a remote server, can I debug it?
+
+Of course you can! Just set the correct `host` and `port` in the `connect` param of the `launch.json` file.