merged Bobs pages

Author: bkoz

documentation/modules/ROOT/assets/images/app-screenshot.png

@@ -1,9 +1,10 @@
-* xref:index.adoc[{counter:module}. Home page]
+* xref:index.adoc[{counter:module}. Introduction]
 ** xref:index.adoc#use-cases[{module}.{counter:submodule1} Use cases]
 ** xref:index.adoc#_the_story_behind_this_solution_pattern[{module}.{counter:submodule1} The story behind this solution pattern]
 ** xref:index#_the_solution[{module}.{counter:submodule1} The solution]
 
 * xref:02-architecture.adoc[{counter:module}. Architecture]
+** xref:02-architecture.adoc#challenges[{module}.{counter:submodule2}. Common Challenges]
 ** xref:02-architecture.adoc#tech_stack[{module}.{counter:submodule2}. Technology stack]
 ** xref:02-architecture.adoc#in_depth[{module}.{counter:submodule2}. An in-depth look at the solution's architecture]
 ** xref:02-architecture.adoc#more_tech[{module}.{counter:submodule2}. More about the technology stack]

documentation/modules/ROOT/assets/images/dataflow.jpg

@@ -1,7 +1,29 @@
 == The story behind this solution pattern
 
-A description of the story that was used to build the demo and architectures of this SP.
+This solution pattern uses a Retreival Augmented Generation (RAG) AI workflow to to summarize financial data
+from a stock symbol API service. The use of AI in this scenario provides a financial analyst
+with a starting point and is especially helpfull when comparing a number of different stock symbols at once.
+Data returned from a stock symbol service is often terse including many acronyms and abreviations. The goal is to 
+demonstrate how AI technologies can be used to summarize the financial data in a way that is 
+more concise and meaningful in a short period of time with minimal human intervention.
+
+The solution begins by using Red Hat Build of Apache Camel to ingest and syncronize publicly aviable financial data
+into a vector database powered by Weaviate. The json formatted data returned from the stock symbol service conists of a company description followed by a number of 
+financial metrics such as revenue, profit, market capitalization, etc.  
+
+The RAG workflow consists of a vector database, an embeddings model (used to convert
+words into vectors) and a large language model (LLM) to summarize the results which is presented to the user. 
+This approach is desirable when information changes frequently or in semi-real time. 
+For example, new stock prices are published every 15 minutes.
+As an alternative to fine tuning an LLM to recognize your private knowledge, Retreival Augmented Generation (RAG) 
+provides a reasonable approach to this solution with good accuracy.
 
 == The Solution
 
-This is a summary of the solution
+This solution patterns consists of the following open source components which are hosted on the Red Hat Openshift 
+container platform:
+
+- Red Hat Build of Apache Camel
+- Weaviate Vector Database
+- The Ollama model server
+- A Cloud Native User Interface built with Gradio

documentation/modules/ROOT/assets/images/rag-architecture.jpg

@@ -7,98 +7,99 @@
 
 Introduction for the architecture of this solution pattern.
 
+[#challenges]
 == Common Challenges 
 
+This solution pattern address the following challenges:
+
+- Integrating private knowledge into a generative AI workflow.
+
+- Capturing and syncronizing near real-time stock exchange data makes periodic fine tuning
+of LLMs prohibitive. 
+
+- Exposing private data sources via externally hosted API services Hosting AI services raises security
+and privacy concerns for most enterprises.
+
 [#tech_stack]
 == Technology Stack
 
 // Change links and text here as you see fit.
-* Red Hat supported products
+* Red Hat supported products:
 ** https://www.redhat.com/en/technologies/cloud-computing/openshift[Red Hat OpenShift]
-** Red Hat Application Foundation
-*** https://access.redhat.com/products/quarkus[Quarkus]
-*** https://www.redhat.com/en/technologies/cloud-computing/openshift/openshift-streams-for-apache-kafka[Kafka Streams]
+*** https://https://developers.redhat.com/products/openshift-dev-spaces/overview[Red Hat Openshift Dev Spaces]
+** https://access.redhat.com/products/red-hat-application-foundations[Red Hat Application Foundation]
+*** https://docs.redhat.com/en/documentation/red_hat_build_of_apache_camel/4.0[Red Hat build of Apache Camel] (included 
+with Red Hat Application Foundation) 
 * Other open source products:
-** https://www.postgresql.org/[PostgreSQL database]
-** https://helm.sh/[Helm]
+** https://weaviate.io/[Weaviate vector database]
+** https://ollama.com/[Ollama Model Server and model files]
+** https://https://huggingface.co/gradio[Gradio]
 
 
 [#in_depth]
 == An in-depth look at the solution's architecture
 
-Technical description including all or some of the following: architecture ir ed diagrams. In-depth details of the decisions made and solutions used. Description of each service and what it is used for. Description of any integration.
-
-=== Using images 
-
-image::red_hat_open-hybrid-cloud.png[width=30%]
+A closer look at the services and components that make up this solution pattern.
 
-{empty}
-
-=== Embedding HTML
-
-++++
-  <br>
-  <h3> Embed HTML by surrounding it with with four +s before and after. </h3>
-  <span>View the ascii doc to learn more</span>
-  <br> 
-++++
+=== Data Flow 
 
+image::dataflow.jpg[width=100%]
 
-=== Different decorators
+==== Ingest Engine
+Data flow begins at the source with stock information made available 
+via a RESTful API service hosted by Alpha Vantage. The ingest engine consisting
+of two Camel services takes care of keeping data fresh in the Weaviate
+vector database. The ingest processes are highly configurable and perform
+filtering and discarding of invalid or null data. As stock symbol information is
+read in, vector embeddings are generated and stored in the Weaviate vector database along
+with the financial entities for each stock symbol. An example json record is available 
+in the https://www.alphavantage.co/query?function=OVERVIEW&symbol=IBM&apikey=demo[AlphaVantage API documentation]. 
 
-[TIP]
-====
-This is a Tip
-====
+==== Vector Database
+The vector database used is Weaviate. Weaviate is a highly performant and scalable open-source vector database 
+that simplifies the development of AI applications. Built-in vector and hybrid search, easy-to-connect machine 
+learning models, and a focus on data privacy enable developers of all levels to build, iterate, and scale AI 
+capabilities faster.
 
-[NOTE]
-====
-This is a NOTE
-====
+==== Machine Learning (ML) models
+This solution pattern makes use of two ML models, an enbeddings model (`all-minilm`) and an LLM (`granite3-dense:8b`)
+which is configurable at run time. The enbeddings model is used to generate vector embeddings for each stock symbol and
+the LLM summarizes the stock information. Granite a series of LLMs developed by IBM, specifically designed 
+for enterprise applications, focusing on business use cases like code generation, summarization, and classification, 
+with a strong emphasis on security and data privacy, all while being open-source under the Apache 2.0 license.
 
-[WARNING]
-====
-This is a WARNING
-====
 
-[IMPORTANT]
-====
-This is IMPORTANT
-====
+image::rag-architecture.jpg[width=100%]
 
+{empty}
 
-=== Creating  tables
- 
-[cols="1a,1a,1a"]
-|===
-| *Column A*  | Column *A* | _Column C_
-|
-* Lorem Ipsum
-* Lorem Ipsum
-
-|
-* Lorem Ipsum
-* Lorem Ipsum
-
-|
-* Lorem Ipsum
-* Lorem Ipsum
-|===
+=== Architecture
 
+=== Ingest Engine
 
+==== Weaviate vector database 
+The Weaviate vector database is installed using the helm installer which allows for enterprise features to be enabled including
+API key token authentication and data sharding. Weaviate's cloud-native design supports horizontal scaling and efficient resource consumption, 
+allowing it to handle large volumes of data and user requests easily. Interested readers are encouraged to find out more 
+about https://www.redhat.com/en/blog/building-powerful-applications-weaviate-and-red-hat-openshift-retrieval-augmented-generation-workflow[the benefits of hosting Weaviate on Openshift].
 
-=== Content that can be copied
+==== Ollama Model Server
+https://github.com/ollama/ollama[Ollama] is a popular and easy to use platform to host and serve LLMs. It supports a number of
+operating systems and provides good integration and compatibility with the open source ecosystem including Weaviate. Ollama
+is deployed on Openshift using a https://github.com/openshift/source-to-image[standard source-to-image workflow]. Details 
+can be found in this repository.
 
-Click below to copy the content
-[.console-input]
-[source,shell script]
-----
-oc version #openshift cli client
-oc login --token=<token> --server=<server>
-----
+==== User Interface
+The UI is written in Python using the Gradio framework and is deployed using Openshift source-to-image workflow. 
+Example queries are presented to the user as pushbuttons to perform semantic
+and generative queries. Users may also enter custom queries and prompts.
 
+==== Developer IDE 
+Provided by Red Hat Openshift DevSpaces, this IDE allows developers to work with the codebase and test their changes
+in a live environment.
 
 [#more_tech]
 == About the Technology Stack
 
-If you want to include more details about the tech stack you used, this is the place.
+https://weaviate.io/[Weaviate] is an open-source vector database that makes it easy to build AI applications. 
+https://ollama.com/[Ollama] is a popular and easy to use platform to host and serve LLMs. 

documentation/modules/ROOT/nav.adoc

@@ -12,23 +12,22 @@ Include here content related to potential existing demos: blogs, articles, recor
 [#demo-video]
 === Watch a demonstration
 
-In this video you can see xpto:
+In this video you can see a brief demonstration:
 
-video::3yULVMdqJ98[youtube, width=800, height=480]
+video::https://people.redhat.com/bkozdemb/downloads/fsi-rag.m4v[width=100%]
 
-Next, you can learn how to walkthrough this demo.
+=== Application Screen Shot
+image::app-screenshot.png[width=100%]
 
-== Run the demonstration
+Next, you can learn how to install this demo.
 
-=== Before getting started
-To run this demo, you will need xpto. Adding to that, make sure to have:
+== Installing and running the demonstration
 
-* ABC
-* XYZ
-* XPTO
+=== Prequisites
+To run this demo, you will need an Openshift v4.16.x cluster with the following resources:
 
-=== Installing the demo
-Installation guide and basic test of the demo installation if needed
+* A worker node that is configured with 8 virtual CPUS, 16GB of RAM and an NVIDIA accelerator with >= 16GB of GPU memory.
+* 100GB of storage available for persistent volumes.
 
-=== Walkthrough guide
-How to run through the demo
+=== Installing the demo
+** Follow the https://github.com/redhat-na-ssa/demo-ai-weaviate[installation guide]

documentation/modules/ROOT/pages/01-pattern.adoc

@@ -4,10 +4,111 @@
 :doctype: book
 
 = Workshop
+During this workshop youwill learn how to:
 
-what is this workshop and what will be learned
+- Get experience with a Weaviate enterprise installation.
+- Learn how to use the Weaviate Python client.
+- Learn how python application are deployed on Openshift
+- Work with the Gradio library to build a user interface.
+- Work with an LLM server on Openshift
+- Understand the various components that make up a RAG solution
 
 == Installing the workshop environment
 === Before getting started
+
+==== Prequisites
+
+- An OpenShift Cluster
+  * Version 4.16 or greater
+  * A worker node with a minimum of 4 CPUs, 16 GB of memory and 
+  a single NVIDIA T4 GPU with 16GB of memory. (AWS `g4dn.xlarge` or equivalent)
+  * The https://docs.openshift.com/container-platform/4.17/web_console/web_terminal/installing-web-terminal.html[web-terminal]
+operator
+- A client system with the following software installed:
+  * https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest[Helm]
+  * https://maven.apache.org/download.cgi[Maven]
+  * https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/[The Openshift `oc` cli]
+- An https://www.alphavantage.co/support/#api-key[AlphaVantage API Key] if you want to periodically 
+refresh the stock symbol data.
+
 === Installing the environment
-== Delivering the workshop
+
+The following services on OpenShift are required:
+
+==== Weaviate Vector Database
+
+- `git clone https://github.com/redhat-na-ssa/demo-ai-weaviate`
+- `cd demo-ai-weaviate`
+- `oc apply -k deploy`
+
+==== Ollama LLM Server
+
+- `oc apply -k ollama/deploy`
+
+Pull the necessary ML models:
+
+Login to the Openshift console, open a terminal window in the `ollama` project
+and run the following commands.
+
+- `curl http://ollama.ollama/api/pull -d '{"model" : "all-minilm"}'`
+
+- `curl http://ollama.ollama/api/pull -d '{"model" : "granite3-dense:8b"}'`
+
+==== Stock Overview Ingestion Engine
+
+===== Caching Proxy
+
+Follow the instructions to install the caching proxy in the `camel` namespace.
+
+- `oc new-project camel`
+- `git clone https://github.com/joshdreagan/av-caching-proxy.git`
+- `cd av-caching-proxy`
+- `cp src/main/jkube/deployment.yml.template src/main/jkube/deployment.yml`
+- `cp src/main/jkube/configmap.yml.template src/main/jkube/configmap.yml`
+- `mvn -P openshift clean package oc:deploy`
+
+The default values for `deployment.yml`, and `configmap.yml` should be fine. 
+
+===== Stock Overview Syncronizer
+
+Install the AlphaVantage syncronizer in the `camel` namespace. 
+
+- `git clone https://github.com/joshdreagan/av-overview-sync.git`
+- `cd av-overview-sync`
+- `cp src/main/jkube/deployment.yml.template src/main/jkube/deployment.yml`
+- `cp src/main/jkube/configmap.yml.template src/main/jkube/configmap.yml`
+- `cp src/main/jkube/secret.yml.template src/main/jkube/secret.yml`
+- `mvn -P openshift clean package oc:deploy`
+
+Configure the `src/main/jkube/configmap.yml` to use the `all-minilm` vectorizer model 
+and the `granite3-dense:8b` generative model.
+
+Update your base64 encoded AlphaVantage API Key in the `src/main/jkube/secret.yml` file.
+
+==== Gradio UI and application.
+
+From a terminal, create an OpenShift application. 
+
+[NOTE]
+====
+Obtain the 
+https://raw.githubusercontent.com/redhat-na-ssa/demo-ai-weaviate/refs/heads/main/deploy/weaviate/configmap.yaml[Weaviate API key]
+and use it to create the RAG application.
+====
+
+- `oc new-app python~https://github.com/redhat-na-ssa/demo-ai-weaviate --name rag --context-dir=/src --env WEAVIATE_API_KEY=your_weaviate_admin-api-key`
+
+Expose the app with an external route and have fun.
+
+- `oc create route edge --service rag --insecure-policy=Redirect`
+
+=== Running the workshop
+
+- Review the https://www.alphavantage.co/query?function=OVERVIEW&symbol=IBM&apikey=demo[IBM stock symbol json] to
+explain the use case.
+- Review the dataflow diagram to explain the workflow.
+- Review the architecture diagram to explain the Openshift services.
+- Run the `rag` application.
+  * Try different search terms and see how the results change.
+  * Vary the limits and see the different number of returned results.
+  * Try different LLM prompts.

documentation/modules/ROOT/pages/02-architecture.adoc

@@ -6,6 +6,9 @@
 
 = Developer Resources
 
-* Add link to the git repo of the code
-* Add links to whitepapers, ebooks, learning paths, product pages
+== Deployment
+* https://github.com/redhat-na-ssa/demo-ai-weaviate[The git repo of the source code]
+
+== Further reading
+* https://www.redhat.com/en/blog/building-powerful-applications-weaviate-and-red-hat-openshift-retrieval-augmented-generation-workflow[A blog post related to running vector databases on Red Hat Openshift]