README instructions for basic AskME features

Signed-off-by: majolr <[email protected]>

Author: majolr

askme/README.md

@@ -13,12 +13,50 @@ AskME is a suite of features designed to empower users to maximize the potential
 
 5.	Knowledge Base Management: Users can create and delete the vector tables.
 
-## Getting Started
+## Prerequisite
 
 You must have an OCI account. [Click here](https://docs.oracle.com/en/cloud/paas/content-cloud/administer/create-and-activate-oracle-cloud-account.html) for more information about Oracle Cloud account creation and activation. Free-tier accounts are currently not supported for the deployment of AskME resources.
 
 There are required OCI resources (see the [Terraform documentation](./terraform/README.md) for more information) that are needed for this tutorial.
 
+## Getting Started: answer questions using your documents
+
+### Create a vector table
+
+In the AskME app, it is easy to use your documents to create a new vector table.
+
+<div style="text-align: center;" >
+    <img src="assets/askme_kb_interface.png" alt="AskME Knowledge Base interface" width="72%" >
+</div>
+
+From the `Knowledge Base Management` tab (<span style="color:red">**1**</span>), under `Create Vector Table` (<span style="color:red">**2**</span>), you can choose to upload one or more documents to AskME (<span style="color:red">**3**</span>):
+- Here is a sample document you can download and use for that purpose: [Onboarding Checklist for New Hires at Nexus Innovations.pdf](./assets/Onboarding%20Checklist%20for%20New%20Hires%20at%20Nexus%20Innovations.pdf)<br />
+- Feel free to use your own documents to try the vector table creation.
+
+After having browsed and selected the relevant files, you can change the vector table name if the default one does not match your needs (<span style="color:red">**4**</span>).<br />
+This name will be used to identify the vector table, and may correspond to the common denominator of all selected files.
+
+Then click on the `Upload` button to start the vector table creation process (<span style="color:red">**5**</span>).<br />
+For the sample document provided earlier, this process should take 30-60 seconds. It may take several minutes if multiple files/bigger files are selected.
+
+Once the vector table has been created, a green message is displayed, explaining that the table creation was successful, and the new table name should be added to the `Selected Vector Tables` list (<span style="color:red">**6**</span>).
+<br />
+
+### Use the vector table to answer questions
+
+Any existing vector table can be used in AskME to generate an accurate answer, with references to the original documents.
+
+<div style="text-align: center;" >
+    <img src="assets/askme_answer_interface.png" alt="AskME free-style answer" width="72%" >
+</div>
+
+From the `Free-style Answer` tab (<span style="color:red">**1**</span>), you can enter your question in the input field (<span style="color:red">**3**</span>).<br />
+Here, we choose to ask a question related to the sample document uploaded in the previous section: *What are the onboarding steps for new hires at Nexus Innovation?*
+
+Please make sure that all vector tables needed for the question are selected in the Knowledge Base Selection area (<span style="color:red">**2**</span>), and then you can click on the `Answer Question` button (<span style="color:red">**4**</span>).
+
+The answer should appear under the `Answer Question` button after a few seconds, followed by a clickable list of document references that have been used to generate the answer.
+
 ## Contributing
 
 This project is open source.  Please submit your contributions by forking this repository and submitting a pull request!  Oracle appreciates any contributions that are made by the open source community.

askme/assets/askme_answer_interface.png

@@ -2,7 +2,7 @@
 
 # Deploy AskME resources with terraform
 
-This section explains how to deploy AskME in your tenancy, using the OCI Cloud Shell and terraform. The following resources are created during the process:
+This section explains how to deploy AskME in your tenancy, using the OCI Cloud Shell and terraform. The following resources are automatically created during the process:
 -	A dynamic group and a policy in the root compartment
 -	A Compartment for the AskME resources
 -	An Object Storage bucket containing two documents
@@ -21,6 +21,8 @@ You need to have the [Administrator role](https://docs.oracle.com/en-us/iaas/Con
 
 ![OCI starting page, developer tools](assets/oci_home_page_dev_tools.png)
 
+![OCI starting page, cloud shell](assets/oci_home_page_cloud_shell.png)
+
 ## Step 2: Get the repository archive
 In the Cloud Shell interface, fetch the tech-content-heatwave repository archive.
 
@@ -29,16 +31,12 @@ Command:
 wget -O tech-content-heatwave.zip -nv https://github.com/oracle-devrel/tech-content-heatwave/archive/refs/heads/tech-content-heatwave_askme.zip
 ```
 
-![Cloud Shell: get repository archive](assets/cloud_shell_fetch.png)
-
 ## Step 3: Unzip the archive
 Command:
 ```
 unzip tech-content-heatwave.zip '*/askme/*' -d tech-content-heatwave
 ```
 
-![Cloud Shell: unzip repository archive](assets/cloud_shell_unzip.png)
-
 ## Step 4: Change directory to the terraform folder
 Command:
 ```
@@ -76,6 +74,8 @@ Set of IPv4 addresses (CIDR notation) allowed to connect to the compute instance
 
 The CIDR notation follows the format: `a.b.c.d/e` where `a`, `b`, `c` and `d` are numbers between 0 and 255, and `e` is a number between 0 and 32. More information about the CIDR block notation in the [Network Overview](https://docs.oracle.com/en-us/iaas/Content/Network/Concepts/overview.htm#:~:text=CIDR%20NOTATION) page.
 
+Use `0.0.0.0/0` to indicate all IP addresses. The prefix is required (for example, include the /32 if specifying an individual IP address). For more information, check the [Security Rules](https://docs.oracle.com/en-us/iaas/Content/Network/Concepts/securityrules.htm) page.
+
 ![Deployment script: IPv4 CIDR block input parameter](assets/cloud_shell_script_ip_cidr.png)
 
 ### Step 6.c: SSH authorized key