WMS 11825 - first version

oci-genai-agent-ext-lab/0-intro/intro.md

@@ -0,0 +1,74 @@
+
+# Introduction
+
+## About This Workshop
+We will extend the features of Oracle Generative AI Agent RAG. The sample will allow to:
+- Search documents like Word/Excel, Images, Video, Audio or Websites (using sitemaps)
+- Build a custom User Interface (UI) with: 
+    - Oracle Digital Assistant
+    - APEX
+    - A python library Streamlit  
+- Run ingestion automatically
+
+We’ll be able to search documents like:
+- Video and Audio files using OCI Speech
+- Images using OCI Vision
+- TIF files (FAX) using OCI Document Understanding
+- Word, Excel, Powerpoint, ... using OCI Functions
+- Websites using Sitemap 
+
+The installation uses Terraform.
+
+![Screenshot](images/when-was-jazz-created.png)
+
+From the lab 2/3/4, we will create 3 user interfaces for the above using the following tools:
+- APEX
+- A Python library Streamlit  
+- Oracle Digital Assistant
+
+Estimated Workshop Time: 90 minutes
+
+### Logical Architecture
+
+This picture shows the processing flow.
+
+![Architecture](images/logical-architecture.png)
+
+It works like this:
+1. A document is uploaded to Object Storage by the user
+1. An event is raised and queued. The event is processed by a Python program running on a VM. Based on the file type, it will send the file to one or more AI services to enrich them and provide searchable text
+1. The searchable text is the result is uploaded to Object Storage "AGENT"
+1. The Generative AI AGENT ingests the new files
+1. The user query the Generative AI Agent
+
+Here's how various file types are processed.
+
+- If the file has the extension **.pdf**, **.txt**, **.csv**, **.md**, the file is copied to the AGENT Object Storage.
+- If the file has the extension **.png**, **.jpg**, **.jpeg**, or **.gif**, it is processed by OCI Vision. The output is stored in the AGENT Object storage 
+- If the file has the extension **.mp4**, **.avi**, **.mp3**, **.wav**, or **.m4a**, it is processed by OCI Speech.
+- If the file has the extension **.tif**, it is processed by OCI Document Understanding.
+- If the file has the extension **.json**, this is an output of the asynchronous AI services such as OCI Speech or OCI Document Understanding. 
+- All other file types like **.doc**, **.docx**, **,xlsx**, **.pptx** are sent to OCI Function with a document parser.
+
+### Physical Architecture
+
+We will install the following architecture using Terraform.
+
+![Integration](images/physical-architecture.png)
+
+### Objectives
+
+- Provision the services needed for the system
+    - Compartment, Object Storage Bucket, Stream, Event, GenAI Agent, AI services and a Virtual Machine
+- Create an OCI Function to convert binary documents (like Word/Excel)
+- Integrate the components into a working system
+- Search for files through several types of user interfaces
+
+**Please proceed to the [next lab.](#next)**
+
+## Acknowledgements 
+
+- **Author**
+    - Marc Gueury, Generative AI Specialist
+    - Anshuman Panda, Generative AI Specialist
+    - Maurits Dijkens, Generative AI Specialist

oci-genai-agent-ext-lab/1-install/install.md

@@ -0,0 +1,273 @@
+# Install the Components
+
+## Introduction
+In this lab, you will install all the components needed for this workshop. Oracle Digital Assistant will be provisioned manually. The rest will be provisioned automatically using a provided Terraform script.
+
+Estimated time: 40 min
+
+### Objectives
+
+- Provision all the cloud components
+
+### Prerequisites
+
+- An OCI Account with sufficient credits where you will perform the lab. (Some of the services used in this lab are not part of the *Always Free* program.)
+- Check that your tenancy has access to the **Frankfurt or London or Chicago Region**
+    - For Paid Tenancy
+        - Click on region on top of the screen
+        - Check that the Frankfurt or London or Chicago Region is there
+        - If not, Click on Manage Regions to add it to your regions list. You need Tenancy Admin right for this.
+        - For ex, click on the US MidWest (Chicago)
+        - Click Subscribe
+
+    ![Chicago Region](images/chicago-region.png)
+
+    - For Free Trial, the HOME region should be Frankfurt or London or Chicago.
+- The lab is using Cloud Shell with Public Network.
+
+    The lab assume that you have access to **OCI Cloud Shell with Public Network access**.
+    To check if you have it, start Cloud Shell and you should see **Network: Public** on the top. If not, try to change to **Public Network**. If it works, there is nothing to do.
+    ![Cloud Shell Public Network](images/cloud-shell-public-network.png)
+
+    OCI Administrator have that right automatically. Or your administrator has maybe already added the required policy.
+    - **Solution:**
+
+        If not, please ask your Administrator to follow this document:
+
+        https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cloudshellintro_topic-Cloud_Shell_Networking.htm#cloudshellintro_topic-Cloud_Shell_Public_Network
+
+        He/She just need to add a Policy to your tenancy :
+
+        ```
+        <copy>
+        allow group <GROUP-NAME> to use cloud-shell-public-network in tenancy
+        </copy>        
+        ```
+
+## Task 1: Prepare to save configuration settings
+
+1. Open a text editor and copy & paste this text into a text file on your local computer. These will be the variables that will be used during the lab.
+
+    ```
+    <copy>
+    List of ##VARIABLES##
+    =====================
+    COMPARTMENT_OCID=(SAMPLE) ocid1.compartment.oc1.amaaaaaaaa
+    TF_VAR_auth_token=(SAMPLE) ABCDEF&é!12345
+    TF_VAR_db_password=(SAMPLE) YOUR_PASSWORD
+    ODA_OCID= (SAMPLE) ocid1.odainstance.oc1.amaaaaaaaa
+
+
+    Terraform Output
+    ================
+
+    AGENT_ENDPOINT_OCID=$AGENT_ENDPOINT_OCID
+
+    -----------------------------------------------------------------------
+    Streamlit:
+    http://12.45.67.89:8080/
+
+    -----------------------------------------------------------------------
+    APEX login:
+
+    APEX Workspace
+    https://abcdefghijklmnop.apigateway.eu-frankfurt-1.oci.customer-oci.com/ords/_/landing
+    Workspace: APEX_APP
+    User: APEX_APP
+    Password: YOUR_PASSWORD
+
+    APEX APP
+    https://abcdefghijklmnop.apigateway.eu-frankfurt-1.oci.customer-oci.com/ords/r/apex_app/apex_app/
+    User: APEX_APP / YOUR_PASSWORD
+    -----------------------------------------------------------------------
+    Oracle Digital Assistant (Web Channel)
+    http://12.45.67.89/
+    </copy>
+    ```
+
+## Task 2: Create a Compartment
+
+The compartment will be used to contain all the components of the lab.
+
+You can
+- Use an existing compartment to run the lab 
+- Or create a new one (recommended)
+
+1. Login to your OCI account/tenancy
+2. Go the 3-bar/hamburger menu of the console and select
+    1. Identity & Security
+    1. Compartments
+    ![Menu Compartment](images/compartment1.png =40%x*)
+2. Click ***Create Compartment***
+    - Give a name: ex: ***genai-agent***
+    - Then again: ***Create Compartment***
+    ![Create Compartment](images/compartment2.png)
+4. When the compartment is created copy the compartment ocid ##COMPARTMENT_OCID## and put it in your notes
+
+
+## Task 3: Run a Terraform script to create the other components.
+
+1. Go to the OCI console homepage
+2. Click the *Developer Tools* icon in the upper right of the page and select *Code Editor*. Wait for it to load.
+3. Check that the Network used is Public. (see requirements)
+4. Check that the Code Editor Architecture is well X86_64.
+    - Go to Actions / Architecture
+    - Check that the current Architecture is well X86_64.
+    - If not change it to X86_64 and confirm. It will restart.
+
+        ![OIC Domain](images/cloud-shell-architecture.png)
+
+5. In the code editor menu, click *Terminal* then *New Terminal*
+6. Run the command below in the terminal
+    ![Menu Compute](images/terraform1.png =50%x*)
+    ````
+    <copy>
+    git clone https://github.com/mgueury/oci-genai-agent-ext.git
+    </copy>
+    ````
+7. Check if you have an Authorisation Token (associated with your profile).
+
+   For more info, see here: https://docs.oracle.com/en-us/iaas/Content/Registry/Tasks/registrygettingauthtoken.htm
+
+   If yes, note it in your notepad. If not, the script below will create it.
+
+7. Run each of the three commands below in the Terminal, one at a time. It will run Terraform to create the rest of the components.
+    ```
+    <copy>
+    cd oci-genai-agent-ext/starter/
+    </copy>
+    ```
+
+    ````
+    <copy>
+    ./starter.sh build
+    </copy>
+    ````
+
+    Answer the question about Authorization Token and Compartment OCID.
+
+8. **Please proceed to the [next lab](#next) while Terraform is running.** 
+    Do not wait for the Terraform script to finish because it takes about 15 minutes and you can complete some steps in the next lab while it's running. However, you will need to come back to this lab when it is done and complete the next step.
+9. When Terraform will finished, you will see settings that you need in the next lab. Save these to your text file. It will look something like:
+
+    ```
+    <copy>    
+    -----------------------------------------------------------------------
+    AGENT_ENDPOINT_OCID=$AGENT_ENDPOINT_OCID
+
+    -----------------------------------------------------------------------
+    Streamlit:
+    http://12.45.67.89:8080/
+
+    -----------------------------------------------------------------------
+    APEX login:
+
+    APEX Workspace
+    https://abcdefghijklmnop.apigateway.eu-frankfurt-1.oci.customer-oci.com/ords/_/landing
+    Workspace: APEX_APP
+    User: APEX_APP
+    Password: YOUR_PASSWORD
+
+    APEX APP
+    https://abcdefghijklmnop.apigateway.eu-frankfurt-1.oci.customer-oci.com/ords/r/apex_app/apex_app/
+    User: APEX_APP / YOUR_PASSWORD
+
+    -----------------------------------------------------------------------
+    Oracle Digital Assistant (Web Channel)
+    http://12.45.67.89/
+    </copy>    
+    ```
+**You may now proceed to the [next lab](#next)**
+
+## Known issues
+
+1. During the terraform run, there might be an error resulting from the compute shapes supported by your tenancy:
+
+    ```
+    <copy>    
+    oci_core_instance.starter_instance: Creating..
+    - Error: 500-InternalError, Out of host capacity.
+    Suggestion: The service for this resource encountered an error. Please contact support for help with service: Core Instance
+    </copy>
+    ```
+
+    Solution:  edit the file *starter/src/terraform/variable.tf* and replace the *availability domain* to one where there are still capacity
+    ```
+    <copy>    
+    OLD: variable availability_domain_number { default = 1 }
+    NEW: variable availability_domain_number { default = 2 }
+    </copy>    
+    ```
+
+    Then rerun the following command in the code editor
+
+    ```
+    <copy>
+    ./starter.sh build
+    </copy>
+    ```
+
+    If it still does not work, to find an availability domain or shape where there are still capacity, try to create a compute manually with the OCI console.
+
+2. During the terraform run, there might be an error resulting from the compute shapes supported by your tenancy:
+
+    ```
+    <copy>    
+    - Error: 404-NotAuthorizedOrNotFound, shape VM.Standard.x86.Generic not found
+    </copy>    
+    ```
+
+    Solution:  edit the file *starter/src/terraform/variable.tf* and replace the *instance_shape* to one where there are still capacity in your tenancy/region
+    ```
+    <copy>    
+    OLD: variable instance_shape { default = "VM.Standard.x86.Generic" }
+    NEW: variable instance_shape { default = "VM.Standard.E4.Flex" }
+    </copy>    
+    ```
+
+    Then rerun the following command in the code editor
+
+    ```
+    <copy>
+    ./starter.sh build
+    </copy>
+    ```
+
+    If it still does not work, to find an availability domain or shape where there are still capacity, try to create a compute manually with the OCI console.    
+
+3. It happened on new tenancy that the terraform script failed with this error:
+
+    ```
+    <copy>    
+    Error: 403-Forbidden, Permission denied: Cluster creation failed. Ensure required policies are created for your tenancy. If the error persists, contact support.
+    Suggestion: Please retry or contact support for help with service: xxxx
+    </copy>    
+    ```
+
+    In such case, just rerunning ./starter.sh build fixed the issue.
+
+4. During terraform:
+    ```
+    <copy>    
+    Error: 409-PolicyAlreadyExists, Policy 'agent-fn-policy' already exists
+    </copy>    
+    ```
+
+    Several persons are probably trying to install this tutorial on the same tenancy.
+
+    Solution:  edit the file *env.sh* and use a unique *TF\_VAR\_prefix*
+    ```
+    <copy>    
+    OLD: export TF_VAR_prefix="agent"
+    NEW: export TF_VAR_prefix="agent2"
+    </copy>    
+    ```
+
+
+## Acknowledgements
+
+- **Author**
+    - Marc Gueury, Generative AI Specialist
+    - Anshuman Panda, Generative AI Specialist
+    - Maurits Dijkens, Generative AI Specialist
+