WMS ID 11661: Using ATP instead of local DB + bug fixing (#747)

* Submited : Create a Large Language Model (LLM) chatbot using Oracle Database 23ai and Generative AI Service.

* Name adjustements

* Folder rename

* Deleted old folder

* Fixed some bugs

* Added the Livelabs version of the workshop

* Fixed some bugs

* Changed to the new LiveLab image + switched model to cohere.command-r-plus

* Updates for the new LiveLabs image

* Fixed image name

* Fixed some prerequisites

* Corrected Liana's job role

* Fixed some conditional inclusions

* Created the ocw24 version of the lab

* Fixed some typos + disclaimers

* Fixed index.html + duplicated names

* Fixed some OCW24 bugs

* Using ATP instead of local DB

* Bug fixing + adding credentials

* Blured personal information

* Hide logos in screenshots

* Small bugfix

---------

Co-authored-by: Bogdan Farca <[email protected]>

ai-chatbot-engine/search+llm/search+llm.md

@@ -45,7 +45,7 @@ fetch approx first {topK} rows only"""
 ```
 In the given SQL query, `topK` represents the number of top results to retrieve. The query selects the payload column along with the cosine distance between the vector column in the specified table (`table_name`) and a provided vector parameter `:vector`, aliasing the distance calculation as `score`. 
 
-By ordering the results by the calculated `score` and using `fetch approx first {topK} rows onl`y, the query efficiently retrieves only the top `topK` results based on their cosine similarity to the provided vector. 
+By ordering the results by the calculated `score` and using `fetch approx first {topK} rows only`, the query efficiently retrieves only the top `topK` results based on their cosine similarity to the provided vector.
 
 ### Step 2: Transforming the question into a vector
 First, we define the question in a new cell.
@@ -166,7 +166,7 @@ In a Retrieval-Augmented Generation (RAG) application, the prompt given to a Lar
     ```python
     <copy>
     # transform docs into a string array using the "paylod" key
-    docs_as_one_string = "\n=========\n".join([doc["text"] for doc in docs])
+    docs_as_one_string = "\n=========\n".join([doc["text"] for doc in results])
     docs_truncated = truncate_string(docs_as_one_string, 1000)
     </copy>
     ```
@@ -200,7 +200,7 @@ In a Retrieval-Augmented Generation (RAG) application, the prompt given to a Lar
 ## Task 3: Call the Generative AI Service LLM
 
 <if type="ocw24">
-0. **If you're running this lab at CloudWorld 2024**
+0. **If you're running this lab at CloudWorld**
 
 In this case, the credentials needed to access the OCI GenAI Service are provided for you. Click on the link below and download the zip file.
 
@@ -327,4 +327,7 @@ You may now **proceed to the next lab**
 * **Contributors** 
    - Liana Lixandru, Principal Digital Adoption Manager, Digital Customer Experience (DCX), EMEA
    - Kevin Lazarz, Senior Manager, Product Management, Database
-* **Last Updated By/Date** -  Bogdan Farca, Sep 2024
+* **Reviewers**
+  - Rahul Gupta, Senior Cloud Engineer, Analytics
+  - Kashif Manzoor, Master Principal Account Cloud Engineer, EMEA AI CoE
+* **Last Updated By/Date** -  Bogdan Farca, Jan 2025

ai-chatbot-engine/setup-23ai/setup-23ai.md

@@ -18,183 +18,61 @@ Estimated Time: 15 minutes
 
 > Note: Any kind of Linux-based system is okay, but you will need to modify the following instructions to suit your specific setup.
 
-## Task 1: Create a compute instance to run the lab
-
-> Note: If you don't know how to create a virtual machine and connect to it via SSH, please [see this lab first](https://livelabs.oracle.com/pls/apex/r/dbpm/livelabs/view-workshop?wid=648&clear=RR,180&session=108750023091545). The following section will only give you a brief overview.
-
-Open your Oracle Cloud Infrastructure Cloud Console and make sure you are in the "US Midwest (Chicago)" or "Frankfurt" region, which is necessary to access the OCI Generative AI services endpoint.
-
-   ![console](images/image1.png)
-
-1. Navigate to the "Compute" section and click on "Instances".
-
-2. Click on "Create Instance".
-
-3. Fill in the necessary details, such as name, compartment, and availability domain.
-
-4. Choose the "Oracle Linux 8" image.
-
-5. Choose a `VM.Standard.E4.Flex` shape.
-
-6. In the Networking section, most of the defaults are perfect for our purposes. However, you will need to scroll down and select the Assign a public IPv4 address option.
-
-6. Configure the security list to allow SSH (port 22) and Jupyter Lab (port 8888). [See here](https://docs.oracle.com/en-us/iaas/Content/Network/Concepts/securitylists.htm) how to do it.
-
-7. Create your instance by clicking on the `Create` button.
-
-8. Connect to your remote instance using SSH.
-   ```
-   <copy>
-   ssh -i <private_ssh_key> opc@<public_ip_address>
-   </copy>
-   ```
-
-## Task 2: Install and configure the database (Oracle Database 23ai Free)
-For simplicity, we will install our database in a container using Podman, a popular container management tool similar to Docker.
-
-### Step 1:  Installing Podman.
-```bash
-<copy>
-sudo dnf config-manager --set-enabled ol8_addons
-sudo dnf install -y podman
-</copy>
-``` 
-
-Now, let's verify our install:
-```bash
-<copy>
-podman --version
-</copy>
-```
-
-### Step 2:  And now, the database itself.
-
-```bash
-<copy>
-podman run 
-    -d 
-    --name 23ai 
-    -p 1521:1521   
-    -e ORACLE_PWD=<the paswword for database admin accounts>   
-    -v oracle-volume:/home/<your home directory>/oradata   
-    container-registry.oracle.com/database/free:latest
-</copy>
-```
-
-Let's verify if it worked:
-```bash
-<copy>
-podman ps
-</copy>
-   ```
-### Step 3: Configuring the database setup.
-
-1. First, start a Bash session inside our newly created container.
-   ```bash
-   <copy>
-   podman exec -it 23ai /bin/bash
-   <copy>
-   ```
-2. Let's connect to the default Oracle 23c Free PDB service and create a tablespace and user by default.
-   ```bash
-   <copy>
-   sqlplus sys@localhost:1521/freepdb1 as sysdba
-   <copy>
-   ```
-   When prompted, enter the password you created when you started your container in the previous step. 
-
-3. Paste the following command inside the SQL*Plus session.
-   ```sql
-   <copy>
-   Create bigfile tablespace tbs2  
-   Datafile 'bigtbs_f2.dbf'  
-   SIZE 1G AUTOEXTEND ON  
-   next 32m maxsize unlimited
-   extent management local segment space management auto;
-   </copy>
-   ``` 
-   ```sql
-   <copy>
-   CREATE UNDO TABLESPACE undots2 DATAFILE 'undotbs_2a.dbf' SIZE 1G AUTOEXTEND ON RETENTION GUARANTEE;
-   </copy>
-   ```
-   ```sql
-   <copy>
-   CREATE TEMPORARY TABLESPACE temp_demo  
-   TEMPFILE 'temp02.dbf' SIZE 1G reuse AUTOEXTEND ON  
-   next 32m maxsize unlimited extent management local uniform size 1m;
-   </copy>
-   ```
-
-   We create now a new user for our vector operations:
-   ```sql
-   <copy>
-   create user vector identified by vector default tablespace tbs2  
-   quota unlimited on tbs2;
-   </copy>
-   ```
-   ```sql
-   <copy>
-   grant DB_DEVELOPER_ROLE to vector;
-   </copy>
-   ```
-
-4. Exiting the sqlplus session:
-   ```sql
-   <copy>
-   exit
-   </copy>
-   ```
-
-5. We have now to allocate memory for the in-memory vector index.
-   ```bash
-   <copy>
-   sqlplus / as sysdba
-   </copy>
-   ```
-   ```sql
-   <copy>
-   create pfile from spfile;
-   </copy>
-   ```
-   ```sql
-   <copy>
-   ALTER SYSTEM SET vector_memory_size = 512M SCOPE=SPFILE;
-   </copy>
-   ```
-   ```sql
-   <copy>
-   shutdown
-   </copy>
-   ```
-   ```sql
-   <copy>
-   startup
-   </copy>
-   ```
-
-   Check if the vector memory size parameter is there after the restart.
-   ```sql
-   <copy>
-   show parameter vector_memory_size;
-   </copy>
-   ```
-   It should show `512M`.
-
-
-6. We now exit the sqlplus session:
-   ```
-   <copy>
-   exit
-   </copy>
-   ```
-
-   And the bash session inside the container:
-   ```
-   <copy>
-   exit
-   </copy>
-   ```
+## Task 1: Install and configure the database (Oracle Database 23ai)
+
+1. Open your Oracle Cloud Infrastructure Cloud Console and make sure you are in the "US Midwest (Chicago)" or "Frankfurt" region, which is necessary to access the OCI Generative AI services endpoint.
+
+2. Click on the hamburger menu and select `Autonomous Transaction Processing" from the "Oracle Database" section.
+
+ ![OCI console](images/image1.png)
+
+3. Click on "Create Autonomous Database" to start the instance creation process. The Create Autonomous Database page is displayed. Select your desired region and compartment. If you are using a sandbox environment (green button) and get a Forbidden message, that indicates you are in the wrong compartment. In the Compartment drop-down list, select your assigned compartment that is listed on the Reservation Information page.
+
+ ![Create ATP](images/image2.png)
+
+4. In the Provide basic information for the Autonomous Database section, specify the following:
+
+- **Compartment**: Select the compartment you just created.
+- **Display name**: Enter a memorable name for the database for display purposes. For this lab, use MyQuickStart.
+- **Database Name**: Use letters and numbers only, starting with a letter. Maximum length is 14 characters. (Underscores not supported.) For this lab, use `VECTORS`.
+
+   In the Choose a workload type section, choose a workload type. Select the workload type for your database from the following choices:
+
+- **Data Warehouse**: Designed to support all standard SQL and business intelligence (BI) tools, and provides all of the performance of the market-leading Oracle Database in an environment that is tuned and optimized for data warehouse workloads
+- **Transaction Processing**: Provides all of the performance of the market-leading Oracle Database in an environment that is tuned and optimized to meet the demands of a variety of applications, including: mission-critical transaction processing, mixed transactions and analytics, IoT, and JSON document store
+- **JSON Database**: It is Oracle Autonomous Transaction Processing, but designed for developing NoSQL-style applications that use JavaScript Object Notation (JSON) documents. You can store up to 20 GB of data other than JSON document collections. There is no storage limit for JSON collections.
+- **APEX**: It is a low cost, Oracle Cloud service offering convenient access to the Oracle APEX platform for rapidly building and deploying low-code applications
+
+   For this workshop select "Transaction Processing" and "Serverless".
+
+   ![DB details](images/image3.png)
+
+5. Enter a password for your admin account (and write it down)
+![ENter password](images/images4.png)
+
+6. In the Choose network access section, select one of the following options:
+- **For this lab**, accept the default, **Secure access from everywhere**.
+- If you want to allow traffic only from the IP addresses and VCNs you specify - where access to the database from all public IPs or VCNs is blocked, select **Secure access from allowed IPs and VCNs only** in the Choose network access area.
+- If you want to restrict access to a private endpoint within an OCI VCN, select **Private endpoint access only** in the Choose network access area.
+- If the Require mutual TLS (mTLS) authentication option is selected, mTLS will be required to authenticate connections to your Autonomous Database. TLS connections allow you to connect to your Autonomous Database without a wallet, if you use a JDBC thin driver with JDK8 or above. See the documentation for network options for options to allow TLS, or to require only mutual TLS (mTLS) authentication.
+
+   ![Networking](images/images5.png)
+
+7. Click on "Create Autonomous Database".
+
+   ![Crest DB](images/images6.png)
+
+   The database is being provisioned now. Let's wait until it's running.
+
+   ![Provisioning](images/images7.png)
+
+8. Once the database is AVAILABLE, click on the "Database connection" button.
+
+   ![Open connection](images/images8.png)
+
+   Now click on "Download wallet" and provide apassword when asked.
+
+   ![Download wallet](images/image9.png)
 
 You may now **proceed to the next lab**
 
@@ -208,4 +86,4 @@ You may now **proceed to the next lab**
 * **Contributors** 
    - Liana Lixandru, Senior Digital Adoption Manager, Digital Customer Experience (DCX), EMEA
    - Kevin Lazarz, Senior Manager, Product Management, Database
-* **Last Updated By/Date** -  Bogdan Farca, May 2024
+* **Last Updated By/Date** -  Bogdan Farca, January 2025

ai-chatbot-engine/setup-python/setup-python.md

@@ -17,7 +17,38 @@ Estimated Time: 15 minutes
 * Basic knowledge of Oracle Cloud Infrastructure (OCI) concepts and consoles
 * Basic Linux knowledge
 
-## Task 1: Install Python
+## Task 1: Create a compute instance to run the lab
+
+> Note: If you don't know how to create a virtual machine and connect to it via SSH, please [see this lab first](https://livelabs.oracle.com/pls/apex/r/dbpm/livelabs/view-workshop?wid=648&clear=RR,180&session=108750023091545). The following section will only give you a brief overview.
+
+Open your Oracle Cloud Infrastructure Cloud Console and make sure you are in the "US Midwest (Chicago)" or "Frankfurt" region, which is necessary to access the OCI Generative AI services endpoint.
+
+   ![console](images/image1.png)
+
+1. Navigate to the "Compute" section and click on "Instances".
+
+2. Click on "Create Instance".
+
+3. Fill in the necessary details, such as name, compartment, and availability domain.
+
+4. Choose the "Oracle Linux 8" image.
+
+5. Choose a `VM.Standard.E4.Flex` shape.
+
+6. In the Networking section, most of the defaults are perfect for our purposes. However, you will need to scroll down and select the Assign a public IPv4 address option.
+
+6. Configure the security list to allow SSH (port 22) and Jupyter Lab (port 8888). [See here](https://docs.oracle.com/en-us/iaas/Content/Network/Concepts/securitylists.htm) how to do it.
+
+7. Create your instance by clicking on the `Create` button.
+
+8. Connect to your remote instance using SSH.
+   ```
+   <copy>
+   ssh -i <private_ssh_key> opc@<public_ip_address>
+   </copy>
+   ```
+
+## Task 2: Install Python
 
 > Note: First, log in to your remote instance via SSH, as described in the previous lab.
 
@@ -85,7 +116,7 @@ Now check if it succeeded :
 ```
 <copy>python --version</copy>
 ```
-## Task 2: Install the required frameworks
+## Task 3: Install the required frameworks
 
 ```bash
 <copy>
@@ -95,7 +126,7 @@ pip install oci
 </copy>
 ```
 
-## Task 3: Install and configure Jupyter Lab
+## Task 4: Install and configure Jupyter Lab
 
 ### Step 1: Install the Jupyter server
 ```

ai-chatbot-engine/vectorization/vectorization.md

@@ -149,12 +149,15 @@ Finally, let's start to code.
 It is now time to insert the prepared chunks into the vector database.
 
 ### Step 1: Create a database connection
+1. Drag and drop the wallet file you downloaded previosly into the Jupyter file pane. Unzip it in folder named "wallet".
+
 1. The connection details should be pinned down in a cell.
    ```python
    <copy>
-   un = "vector"
-   pw = "vector"
-   <if type="freetier">cs = "localhost/FREEPDB1"</if><if type="livelabs">cs = "host.containers.internal/FREEPDB1"</if><if type="ocw24">cs = "host.containers.internal/FREEPDB1"</if>
+   un = <your database username>
+   pw = <your database password>
+   <if type="livelabs">cs = "host.containers.internal/FREEPDB1"</if>
+   <if type="ocw24">cs = "host.containers.internal/FREEPDB1"</if>
    </copy>
    ```
    > Note: Use the exact username and password you set up for the database in the previous lab.
@@ -163,13 +166,19 @@ It is now time to insert the prepared chunks into the vector database.
    ```python
    <copy>
    import oracledb
-
-   connection = oracledb.connect(user=un, password=pw, dsn=cs)
+   <if type="freetier">
+   dsn = '<NAME OF THE DATABASE>_high' 
+
+   connection = oracledb.connect(
+      config_dir='../Graphs/wallet',
+      user=un,
+      password=pw,
+      dsn=dsn,
+      wallet_location='./wallet',
+      wallet_password=<your wallet password>)
+   </if><if type="livelabs">connection = oracledb.connect(user=un, password=pw, dsn=cs)</if><if type="ocw24">connection = oracledb.connect(user=un, password=pw, dsn=cs)</if>
    </copy>
    ```
-   ![connection](images/image15.png)
-
-   > Note: Don't forget to run each cell by pressing Shift + Enter while inside it.
 
 ### Step 2: Create the `faqs` table
 We need a table inside our database to store our vectors and metadata.
@@ -302,4 +311,4 @@ You may now **proceed to the next lab**
    - Liana Lixandru, Principal Digital Adoption Manager, Digital Customer Experience (DCX), EMEA
    - Wojciech Pluta, Director, Technical Product Marketing
    - Kevin Lazarz, Senior Manager, Product Management, Database
-* **Last Updated By/Date** -  Bogdan Farca, Sep 2024
+* **Last Updated By/Date** -  Bogdan Farca, January 2025