Docos (#8)

* Full Walkthrough, Database and Model Configuration
* Feedback implemented

README.md

@@ -4,7 +4,7 @@
 
 ## Description
 
-The **Oracle AI Microservices Sandbox** provides a streamlined environment where developers and data scientists can explore the potential of Generative Artificial Intelligence (GenAI) combined with Retrieval-Augmented Generation (RAG) capabilities. By integrating the **Oracle Database** for Vector Storage, the Sandbox enables users to enhance existing Large Language Models (LLMs) through RAG. This method significantly improves the performance and accuracy of AI models, helping to avoid common issues such as knowledge cutoff and hallucinations.
+The **Oracle AI Microservices Sandbox** provides a streamlined environment where developers and data scientists can explore the potential of Generative Artificial Intelligence (GenAI) combined with Retrieval-Augmented Generation (RAG) capabilities. By integrating **Oracle Database 23ai** AI Vector Search, the Sandbox enables users to enhance existing Large Language Models (LLMs) through RAG.
 
 ## Getting Started
 

app/requirements.txt

@@ -32,4 +32,5 @@ pypdf==4.3.1
 
 ## For Licensing Purposes... this ensures no GPU modules
 -f https://download.pytorch.org/whl/cpu/torch
-torch==2.4.1+cpu
+torch==2.4.1+cpu ; sys_platform == "linux"
+torch==2.2.2 ; sys_platform == "darwin"

app/src/content/model_config.py

@@ -75,6 +75,15 @@ def update_lm_model_config():
 #############################################################################
 def main():
     """Streamlit GUI"""
+    css = """
+    <style>
+        div[data-testid="element-container"] .stCheckbox {
+            min-height: 2.5em !important;
+        }
+    </style>
+    """
+    st.markdown(css, unsafe_allow_html=True)
+
     initialise_streamlit()
 
     st.header("Language Models")

app/src/modules/oci_utils.py

@@ -142,6 +142,8 @@ def get_namespace(config, retries=True):
         raise OciException("Invalid Config - Disabling OCI") from ex
     except oci.exceptions.ServiceError as ex:
         raise OciException("AuthN Error - Disabling OCI") from ex
+    except oci.exceptions.RequestException as ex:
+        raise OciException("No Network Access - Disabling OCI") from ex
     except FileNotFoundError as ex:
         raise OciException("Invalid Key Path") from ex
     except UnboundLocalError as ex:

docs/content/configuration/db_config.md

@@ -1,17 +1,14 @@
 ---
-title: 'Database Configuration'
+title: "Database Configuration"
 date: 2024-09-10T13:57:37Z
 draft: false
 ---
 
-{{< hint type=[warning] icon=gdoc_fire title="10-Sept-2024: Documentation In-Progress..." >}}
-Thank you for your patience as we work on updating the documentation. Please check back soon for the latest updates.{{< /hint >}}
-
-To use the Retrieval-Augmented Generation (RAG) functionality of the Sandbox, you will need to setup/enable an [embedding model](model_config) and have access to an **Oracle Database 23ai**.  Both the [Always Free Oracle Autonomous Database Serverless (ADB-S)](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/autonomous-always-free.html) and the [Oracle Database 23ai Free](https://www.oracle.com/uk/database/free/get-started/) are supported.  They are a great way to get up and running quickly.
+To use the Retrieval-Augmented Generation (RAG) functionality of the Sandbox, you will need to setup/enable an [embedding model](model_config) and have access to an **Oracle Database 23ai**. Both the [Always Free Oracle Autonomous Database Serverless (ADB-S)](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/autonomous-always-free.html) and the [Oracle Database 23ai Free](https://www.oracle.com/uk/database/free/get-started/) are supported. They are a great, no-cost, way to get up and running quickly.
 
 ## Configuration
 
-The database can either be configured using environment variables or through the Sandbox interface.
+The database can either be configured using environment variables or through the **Sandbox** interface.
 
 ### Sandbox Interface
 
@@ -20,40 +17,41 @@ To configure the Database from the Sandbox, navigate to `Configuration -> Databa
 ![Database Config](../images/db_config.png)
 
 Provide the following input:
-- DB Username: The pre-created [database username](#database-user) where the embeddings will be stored
-- DB Password: The password for the `DB Username`
-- Database Connect String: The full connection string or [TNS Alias](#using-a-wallettns_admin-directory) for the Database.  This is normally in the form of `(description=... (service_name=<service>))`.
-- Wallet Password: If the connection to the database uses mTLS, provide the wallet password.  **NOTE**: Review [Using a Wallet](#using-a-wallettns_admin-directory) for additional setup instructions.
+
+- **DB Username**: The pre-created [database username](#database-user) where the embeddings will be stored
+- **DB Password**: The password for the **DB Username**
+- **Database Connect String**: The full connection string or [TNS Alias](#using-a-wallettns_admin-directory) for the Database. This is normally in the form of `(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=<hostname>)(PORT=<port>))(CONNECT_DATA=(SERVICE_NAME=<service_name>)))` or `//<hostname>:<port>/<service_name>`.
+- **Wallet Password** (_Optional_): If the connection to the database uses mTLS, provide the wallet password. {{< icon "gdoc_star" >}}Review [Using a Wallet](#using-a-wallettns_admin-directory) for additional setup instructions.
 
 Once all fields are set, click the `Save` button.
 
 ### Environment Variables
 
 The following environment variables can be set, prior to starting the Sandbox, to automatically configure the database:
 
-- DB_USERNAME: The pre-created [database username](#database-user) where the embeddings will be stored
-- DB_PASSWORD: The password for the `DB Username`
-- DB_DSN: The full connection string or [TNS Alias](#using-a-wallettns_admin-directory) for the Database.  This is normally in the form of `(description=... (service_name=<service>))`.
-- DB_WALLET_PASSWORD: If the connection to the database uses mTLS, provide the wallet password.  **NOTE**: Review [Using a Wallet](#using-a-wallettns_admin-directory) for additional setup instructions.
+- **DB_USERNAME**: The pre-created [database username](#database-user) where the embeddings will be stored
+- **DB_PASSWORD**: The password for the `DB Username`
+- **DB_DSN**: The connection string or [TNS Alias](#using-a-wallettns_admin-directory) for the Database. This is normally in the form of `(description=... (service_name=<service_name>))` or `//host:port/service_name`.
+- **DB_WALLET_PASSWORD** (_Optional_): If the connection to the database uses mTLS, provide the wallet password. {{< icon "gdoc_star" >}}Review [Using a Wallet](#using-a-wallettns_admin-directory) for additional setup instructions.
 
 For Example:
 
 ```bash
 export DB_USERNAME="DEMO"
 export DB_PASSWORD=MYCOMPLEXSECRET
-export DB_DSN="(description=(address=(protocol=tcps)(port=1521)(host=database.host.com))(connect_data=(service_name=SANDBOXDB)))"
+export DB_DSN="//localhost:1521/SANDBOXDB"
 export DB_WALLET_PASSWORD=MYCOMPLEXWALLETSECRET
 ```
 
 ## Using a Wallet/TNS_ADMIN Directory
 
-For mTLS connectivity, or to specify a TNS Alias instead of a full connect string, you can set the `TNS_ADMIN` environment variable to the location where the SQL*Net files are staged.  Alternatively, you can copy those files to the `app/src/tns_admin` directory.
+For mTLS connectivity, or to specify a TNS Alias instead of a full connect string, you can set the `TNS_ADMIN` environment variable to the location where the SQL\*Net files are staged. Alternatively, you can copy those files to the `app/src/tns_admin` directory.
 
 If using and ADB-S wallet, unzip the contents to one of the above (`TNS_ADMIN` or `app/src/tns_admin`) directories.
 
 ## Database User
 
-A database user is required to store the embeddings used for RAG into a Vector Store. A non-privileged user should be used for this purpose, using the below syntax as an example:
+A database user is required to store the embeddings, used for **RAG**, into the Oracle Database. A non-privileged user should be used for this purpose, using the below syntax as an example:
 
 ```sql
 CREATE USER "DEMO" IDENTIFIED BY MYCOMPLEXSECRET
@@ -66,6 +64,6 @@ ALTER USER "DEMO" QUOTA UNLIMITED ON DATA;
 
 Replace "DEMO" as required.
 
-{{< hint type=[tip] icon=gdoc_fire title="Multiple Users" >}}
+{{< hint type=[tip] icon=gdoc_info_outline title="Multiple Users" >}}
 Creating multiple users in the same database allows developers to separate their experiments simply by changing the "Database User:"
 {{< /hint >}}

docs/content/configuration/model_config.md

@@ -4,46 +4,68 @@ date = 2024-09-11T07:30:34Z
 draft = false
 +++
 
-{{< hint type=[warning] icon=gdoc_fire title="10-Sept-2024: Documentation In-Progress..." >}}
-Thank you for your patience as we work on updating the documentation. Please check back soon for the latest updates.{{< /hint >}}
-
 ## Supported Models
 
-At a minimum, a Large Language Model (LLM) must be configured in **Oracle AI Microservices Sandbox** for basic functionality. For Retrieval-Augmented Generation (RAG), an embedding model will also need to be configured.
+At a minimum, a Large _Language Model_ (LLM) must be configured in **Oracle AI Microservices Sandbox** for basic functionality. For Retrieval-Augmented Generation (**RAG**), an _Embedding Model_ will also need to be configured.
 
 {{< hint type=[note] icon=gdoc_info_outline title="Additional Model Support" >}}
 If there is a specific model that you would like to use with the **Oracle AI Microservices Sandbox**, please [open an issue in GitHub](https://github.com/oracle-samples/oaim-sandbox/issues/new).{{< /hint >}}
 
-| Model                          | Type  | API                                           | On-Premises |
-| ------------------------------ | ----- | --------------------------------------------- | ----------- |
-| llama3.1                       | LLM   | [ChatOllama](#additional-information)         | X           |
-| gpt-3.5-turbo                  | LLM   | [OpenAI](#additional-information)             |             |
-| gpt-4o-mini                    | LLM   | [OpenAI](#additional-information)             |             |
-| gpt-4                          | LLM   | [OpenAI](#additional-information)             |             |
-| gpt-4o                         | LLM   | [OpenAI](#additional-information)             |             |
-| llama-3-sonar-small-32k-chat   | LLM   | [ChatPerplexity](#additional-information)     |             |
-| llama-3-sonar-small-32k-online | LLM   | [ChatPerplexity](#additional-information)     |             |
-| mxbai-embed-large              | Embed | [OllamaEmbeddings](#additional-information)   | X           |
-| nomic-embed-text               | Embed | [OllamaEmbeddings](#additional-information)   | X           |
-| all-minilm                     | Embed | [OllamaEmbeddings](#additional-information)   | X           |
-| thenlper/gte-base              | Embed | [HuggingFaceEndpointEmbeddings](#additional-information) | X|
-| text-embedding-3-small         | Embed | [OpenAIEmbeddings](#additional-information)   |             |
-| text-embedding-3-large         | Embed | [OpenAIEmbeddings](#additional-information)   |             |
+| Model                          | Type  | API                                                      | On-Premises |
+| ------------------------------ | ----- | -------------------------------------------------------- | ----------- |
+| llama3.1                       | LLM   | [ChatOllama](#additional-information)                    | X           |
+| gpt-3.5-turbo                  | LLM   | [OpenAI](#additional-information)                        |             |
+| gpt-4o-mini                    | LLM   | [OpenAI](#additional-information)                        |             |
+| gpt-4                          | LLM   | [OpenAI](#additional-information)                        |             |
+| gpt-4o                         | LLM   | [OpenAI](#additional-information)                        |             |
+| llama-3-sonar-small-32k-chat   | LLM   | [ChatPerplexity](#additional-information)                |             |
+| llama-3-sonar-small-32k-online | LLM   | [ChatPerplexity](#additional-information)                |             |
+| mxbai-embed-large              | Embed | [OllamaEmbeddings](#additional-information)              | X           |
+| nomic-embed-text               | Embed | [OllamaEmbeddings](#additional-information)              | X           |
+| all-minilm                     | Embed | [OllamaEmbeddings](#additional-information)              | X           |
+| thenlper/gte-base              | Embed | [HuggingFaceEndpointEmbeddings](#additional-information) | X           |
+| text-embedding-3-small         | Embed | [OpenAIEmbeddings](#additional-information)              |             |
+| text-embedding-3-large         | Embed | [OpenAIEmbeddings](#additional-information)              |             |
 
 ## Configuration
 
-To configure an LLM from the Sandbox, navigate to `Configuration -> Models`:
+The models can either be configured using environment variables or through the **Sandbox** interface. To configure models through environment variables, please read the [Additional Information](#additional-information) about the specific model you would like to configure.
+
+To configure an LLM or embedding model from the **Sandbox**, navigate to `Configuration -> Models`:
+
+![Model Config](../images/model_config.png)
+
+Here you can configure both Large _Language Models_ and _Embedding Models_. Set the API Keys and API URL as required. You can also Enable and Disable models.
+
+### API Keys
+
+Third-Party cloud models, such as [OpenAI](https://openai.com/api/) and [Perplexity AI](https://docs.perplexity.ai/getting-started), require API Keys. These keys are tied to registered, funded accounts on these platforms. For more information on creating an account, funding it, and generating API Keys for third-party cloud models, please visit their respective sites.
+
+![Cloud Model API Keys](../images/model_third-party-api-key.png)
+
+On-Premises models, such as those from [Ollama](https://ollama.com/) or [HuggingFace](https://huggingface.co/) usually do not require API Keys. These values can be left blank.
+
+![On-Premises Model API Keys](../images/model_on-prem-api-key.png)
+
+### API URL
+
+When using an on-premises model, for performance purposes, they should be running on hosts with GPUs. As the **Sandbox** does not require GPUs, often is the case that the API URL for these models will be the IP or hostname address of a remote host. Specify the API URL and Port of the remote host.
+
+![On-Premises Model API URL](../images/model_on-prem-api-url.png)
 
 ## Additional Information
+
 {{< tabs "uniqueid" >}}
 {{< tab "Ollama" >}}
-# Ollama 
+
+# Ollama
+
 [Ollama](https://ollama.com/) is an open-source project that simplifies the running of LLMs and Embedding Models On-Premises.
 
-When configuring an Ollama model in the Sandbox, set the `API Server` URL (e.g `http://127.0.0.1:11434`) and leave the API Key blank. Substitute the IP Address with IP of where Ollama is running.
+When configuring an Ollama model in the **Sandbox**, set the `API Server` URL (e.g `http://127.0.0.1:11434`) and leave the API Key blank. Substitute the IP Address with IP of where Ollama is running.
 
-{{< hint type=[tip] icon=gdoc_fire title="Auto Setup/Enable" >}}
-You can set the following environment variable to automatically set the `API Server` URL and enable Ollama models (change the IP address as required):
+{{< hint type=[tip] icon=gdoc_star title="Auto Setup/Enable" >}}
+You can set the following environment variable to automatically set the `API Server` URL and enable Ollama models (change the IP address and Port, as applicable to your environment):
 
 ```shell
 export ON_PREM_OLLAMA_URL=http://127.0.0.1:11434
@@ -76,13 +98,14 @@ ollama serve
 For more information and instructions on running Ollama on other platforms, please visit the [Ollama GitHub Repository](https://github.com/ollama/ollama/blob/main/README.md#quickstart).
 
 {{< /tab >}}
-{{< tab "HuggingFace" >}} 
+{{< tab "HuggingFace" >}}
+
 # HuggingFace
 
 [HuggingFace](https://huggingface.co/) is a platform where the machine learning community collaborates on models, datasets, and applications. It provides a large selection of models that can be run both in the cloud and On-Premises.
 
-{{< hint type=[tip] icon=gdoc_fire title="Auto Setup/Enable" >}}
-You can set the following environment variable to automatically set the `API Server` URL and enable HuggingFace models (change the IP address as required):
+{{< hint type=[tip] icon=gdoc_star title="Auto Setup/Enable" >}}
+You can set the following environment variable to automatically set the `API Server` URL and enable HuggingFace models (change the IP address and Port, as applicable to your environment):
 
 ```shell
 export ON_PREM_HF_URL=http://127.0.0.1:8080
@@ -125,31 +148,34 @@ Example of running thenlper/gte-base in a container:
    docker inspect hftei-gte-base | grep IPA
    ```
 
-   **NOTE:** if there is no IP, use 127.0.0.1 
-{{< /tab >}}
-{{< tab "OpenAI" >}}
+   **NOTE:** if there is no IP, use 127.0.0.1
+   {{< /tab >}}
+   {{< tab "OpenAI" >}}
+
 # OpenAI
 
-[OpenAI](https://openai.com/api/) is an AI research organization behind the popular, online ChatGPT chatbot. To use OpenAI models, you will need to sign-up, purchase credits, and provide the Sandbox an API Key.
+[OpenAI](https://openai.com/api/) is an AI research organization behind the popular, online ChatGPT chatbot. To use OpenAI models, you will need to sign-up, purchase credits, and provide the **Sandbox** an API Key.
 
-**NOTE:** OpenAI is a cloud model and you should familiarize yourself with their Privacy Policies if using it to experiment with private, sensitive data in the Sandbox.
+**WARNING:** OpenAI is a cloud model and you should familiarize yourself with their Privacy Policies if using it to experiment with private, sensitive data in the **Sandbox**.
 
-{{< hint type=[tip] icon=gdoc_fire title="Auto Setup/Enable" >}}
+{{< hint type=[tip] icon=gdoc_star title="Auto Setup/Enable" >}}
 You can set the following environment variable to automatically set the `API Key` and enable OpenAI models:
 
 ```shell
 export OPENAI_API_KEY=<super-secret API Key>
 ```
+
 {{< /hint >}}
 {{< /tab >}}
 {{< tab "Perplexity AI" >}}
+
 # Perplexity AI
 
-[Perplexity AI](https://docs.perplexity.ai/getting-started) is an AI-powered answer engine. To use Perplexity AI models, you will need to sign-up, purchase credits, and provide the Sandbox an API Key.
+[Perplexity AI](https://docs.perplexity.ai/getting-started) is an AI-powered answer engine. To use Perplexity AI models, you will need to sign-up, purchase credits, and provide the **Sandbox** an API Key.
 
-**NOTE:** Perplexity AI is a cloud model and you should familiarize yourself with their Privacy Policies if using it to experiment with private, sensitive data in the Sandbox.
+**WARNING:** Perplexity AI is a cloud model and you should familiarize yourself with their Privacy Policies if using it to experiment with private, sensitive data in the **Sandbox**.
 
-{{< hint type=[tip] icon=gdoc_fire title="Auto Setup/Enable" >}}
+{{< hint type=[tip] icon=gdoc_star title="Auto Setup/Enable" >}}
 You can set the following environment variable to automatically set the `API Key` and enable Perplexity models:
 
 ```shell