various small updates

Author: jamesfalkner

content/modules/ROOT/pages/module-devhub.adoc

@@ -73,9 +73,9 @@ The output should look similar to the following.
 [source,bash]
 ----
 ....
- --/ __ \/ / / / _ | / _ \/ //_/ / / / __/ 
- -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \   
---\___\_\____/_/ |_/_/|_/_/|_|\____/___/   
+ --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
+ -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
+--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
 INFO  [io.quarkus] (Quarkus Main Thread) insurance-app 1.0.0-SNAPSHOT on JVM (powered by Quarkus xx.xx.xx) started in 19.615s. Listening on: http://0.0.0.0:8080
 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [agroal, cdi, hibernate-orm, hibernate-orm-panache, jdbc-h2, langchain4j, langchain4j-ollama, langchain4j-openai, langchain4j-websockets-next, narayana-jta, quinoa, qute, rest, rest-client, rest-client-jackson, rest-jackson, smallrye-context-propagation, vertx, websockets-next]
@@ -85,10 +85,22 @@ Tests paused
 Press [e] to edit command line args (currently ''), [r] to resume testing, [o] Toggle test output, [:] for the terminal, [h] for more options>
 ----
 
-Validate your local Parasol application against the production version by accessing the https://{user}-parasol-insurance-parasol-webui.{openshift_cluster_ingress_domain}[Parasol web page^].
+Validate your local Parasol application against the production version by accessing the https://{user}-parasol-insurance-parasol-webui.{openshift_cluster_ingress_domain}[Parasol web page^] (it may take up to a minute to come up - wait for the "Listening on..." message as shown above).
 
 image::devhub/parasol_ui_web.png[]
 
+==== Preview the changes you need to make
+
+To add the new feature, you will either create or edit the following files. Use this list as a checklist to ensure you've made all the changes. If you get errors when you try to run the app, be sure each file was changed as described in the instructions below!
+
+* `src/main/java/org/parasol/model/Email.java` - A Java record defining an incoming email from a customer
+* `src/main/java/org/parasol/model/EmailResponse.java` - A Java record defining a response (subject+message)
+* `src/main/java/org/parasol/ai/EmailService.java` - interface for interacting with the underlying LLM
+* `src/main/java/org/parasol/resources/EmailResource.java` - A REST-like web frontend interface
+* `src/main/resources/application.properties` - The Quarkus configuration where you'll define the parameters for connecting to the LLM inference service
+* `src/main/webui/src/app/components/EmailGenerate/EmailGenerate.tsx` - A React web component providing a simple interface for providing a customer email
+* `src/main/webui/src/app/routes.tsx` - A list of React routes to which you'll add the new Email generator component
+
 ==== Create Java records beans
 
 Create a new Java record, `Email.java` in the `src/main/java/org/parasol/model` directory to carry email data in a concise and immutable way.
@@ -137,26 +149,26 @@ import dev.langchain4j.service.SystemMessage;
 import dev.langchain4j.service.UserMessage;
 import io.quarkiverse.langchain4j.RegisterAiService;
 
-@RegisterAiService(modelName = "parasol-email") 
+@RegisterAiService(modelName = "parasol-email")<1>
 public interface EmailService {
-    @SystemMessage(""" 
+    @SystemMessage("""<2>
       You are a helpful, respectful and honest assistant named "Parasol Assistant".
 
       You are responding to customer emails. Provide a friendly response that is written by Parasol. The response should thank them for being a customer. Include information about when parasol insurance was founded.
-      
+
       Your response must look like the following JSON:
 
       {
         "subject": [A good one-line greeting],
         "message": [Your response, summarizing the information they gave and ask the customer for any follow-up information needed to file a claim]
       }
       """)
-    EmailResponse chat(@UserMessage String claim); 
+    EmailResponse chat(@UserMessage String claim);<3>
 }
 ----
-<1> *@RegisterAiService* annotation is pivotal for registering the AI Service, represented as a Java interface.
-<2> *@SystemMessage* annotation defines the scope and initial instructions, serving as the first message sent to the LLM. It delineates the AI service's role in the interaction.
-<3> *@UserMessage* annotation defines primary instructions dispatched to the LLM. It typically encompasses requests and the expected response format.
+<1> `@RegisterAiService` annotation is pivotal for registering the AI Service, represented as a Java interface.
+<2> `@SystemMessage` annotation defines the scope and initial instructions, serving as the first message sent to the LLM. It delineates the AI service's role in the interaction.
+<3> `@UserMessage` annotation defines primary instructions dispatched to the LLM. It typically encompasses requests and the expected response format.
 
 ==== Create Jakarta REST resource
 
@@ -207,7 +219,7 @@ quarkus.langchain4j.openai.parasol-email.timeout=600s<3>
 quarkus.langchain4j.openai.parasol-email.chat-model.model-name=parasol-instruct<4>
 quarkus.langchain4j.openai.parasol-email.base-url=http://parasol-instruct-predictor.aiworkshop.svc.cluster.local:8080/v1<5>
 ----
-<1> Specify the model provider (e.g., openai, huggingface). Note that you use the Open AI API specification when you connedt to the LLM (parasol-instruct) inference endpoint
+<1> Specify the model provider (e.g., openai, huggingface). Note that you use the Open AI API specification when you connect to the LLM (parasol-instruct) inference endpoint
 <2> Set the model temperature. Temperature is a parameter used in natural language processing models to increase or decrease the “confidence” a model has in its most likely response
 <3> Specify the timeout between question and response in the LLM
 <4> Specify the model name to connect to
@@ -313,7 +325,7 @@ This interface allows customer service representatives to copy and paste the cus
 
 ==== Add a new menu item in the navigation bar
 
-Open the `routes.tsx` file in the `src/main/webui/src/app` directory and `uncomment` the following code out in line *8* and *89 - 95* to show the new menu item. 
+Open the `routes.tsx` file in the `src/main/webui/src/app` directory and `uncomment` the following code out in line *8* and *89 - 95* to show the new menu item.
 
 [NOTE]
 ====

content/modules/ROOT/pages/module-ilab.adoc

@@ -161,7 +161,7 @@ Now that we understand the constructs of the taxonomy's knowledge, let's go ahea
 
 ==== Open the `instructlab` taxonomy directory in Visual Studio Code
 
-You can open VSCode by following the instructions below:
+Open VSCode by running the below command. Even if you already have VSCode open, you should run this command to open the taxonomy folder (notice the `--reuse-window` flag).
 
 [.console-input]
 [source,bash,subs="+attributes,macros+"]
@@ -272,6 +272,8 @@ knowledge/economy/finance/insurance/parasol/qna.yaml
 Taxonomy in /home/instruct/.local/share/instructlab/taxonomy is valid :)
 ----
 
+NOTE: If you see an error such as `no new line character at the end of the file`, simply place your cursor at the end of the last line of the taxonomy file and press kbd:[ENTER] to add a new line, and re-run the `ilab diff` command.
+
 If you do not see output similar to above, you may not have added in all of the Q&A file. This is important as the model will use this file to generate synthetic data in the next section.
 
 == Generating Synthetic Training Data & Training the New Model

content/modules/ROOT/pages/module-prompt.adoc

@@ -38,9 +38,9 @@ You might choose to use prompt engineering over other techniques if you're looki
 
 There are many tools and approaches available to you as the AI application developer to interface an LLM.  We will briefly review a few of these and then make a recommendation for you to follow with the subsequent steps of this module.
 
-Before jumping into specific tools, let's review the basics of interfacing with an LLM through a chat or agentic experience.  Since LLMs can often support a wide variety of use cases and personas, it is important that the LLM receive clear, upfront guidance to define its objectives, constraints, persona, and tone.  These instructions are provided in natural language format that are specified in the "System Prompt". Once a System Prompt is defined and a chat session begins, the System Prompt cannot be changed.
+Before jumping into specific tools, let's review the basics of interfacing with an LLM through a chat or agentic experience.  Since LLMs can often support a wide variety of use cases and personas, it is important that the LLM receive clear, upfront guidance to define its objectives, constraints, persona, and tone.  These instructions are provided using natural language specified in the "System Prompt". Once a System Prompt is defined and a chat session begins, the System Prompt cannot be changed.
 
-Depending on use case, it may be necessary for the LLM to produce a more creative or a more predictable response to the user message.  Temperature is a floating point number, usually between 0 and 1, that is used to steer the model accordingly.  Lower temperature values (such as 0) are more predictable and higher values (such as 1) are more creative, although even at 0 LLMs will never product 100% repeatable responses.  Many tools simply use 0.8 as a default.
+Depending on use case, it may be necessary for the LLM to produce a more creative or a more predictable response to the user message.  Temperature is a floating point number, usually between 0 and 1, that is used to steer the model accordingly.  Lower temperature values (such as 0) are more predictable and higher values (such as 1) are more creative, although even at 0 LLMs will never produce 100% repeatable responses.  Many tools simply use 0.8 as a default.
 
 Lastly, while experimenting with LLMs, especially with inferencing servers without a GPU, it is recommended to constrain the LLM from producing overly verbose responses by setting the Max Tokens to an appropriate threshold.  This also helps coach the LLM to be more concise with its responses, which can be helpful during testing.
 
@@ -99,7 +99,7 @@ For this section we will be exercising the model with some basic prompts to gain
 
 === Open Dev UI with LangChain4j Chat
 
-Open your workspace in the Dev Spaces per the instructions in the prior section.
+Open your workspace in Dev Spaces per the instructions in the prior section.
 
 Spawn a terminal window within the IDE by clicking on the icon with three parallel bars in the upper left corner of the screen.  Choose "Terminal" and then "New Terminal" menu entry from the list.
 
@@ -397,7 +397,7 @@ If you haven't created *a new Gen AI email service* in the previous module yet,
 sh ${PROJECT_SOURCE}/scripts/create-email-ai-service.sh
 ----
 
-Access the https://parasol-app-{user}-dev-parasol-app-{user}-dev.{openshift_cluster_ingress_domain}[Parasol web page^] to verify the Gen AI email service.
+Access the https://parasol-app-{user}-dev-parasol-app-{user}-dev.{openshift_cluster_ingress_domain}[Parasol web page^],to verify the Gen AI email service. To access the email service, click on the `Email Generate` tab on the left and use it in the following sections:
 ====
 
 ==== Generate an email for `new claim #1` to the [email protected]
@@ -540,19 +540,17 @@ During a prior workshop activity, email response generation using LangChain4j wa
 
 image::prompt/parasol-generate-email-response-form.png[Generate Email Response Web Form]
 
-IMPORTANT: Section 5 of the Parasol AI Developer Workflow module provides steps for introducing a new email feature into the application using generative AI.  The following section builds upon this feature with new capabilities. If you have not yet completed that section, you should either do so now or use the following script to automatically incorporate those changes for modification here.
-
 The Parasol Insurance application is invoking the LLM using LangChain4j's AI Service framework.  This approach leverages Java Interfaces created by the user with annotations that define the prompt using a String.  Let's open the AI Service that was previously created for Email Response Generation:
 
-`parasol-insurance/app/src/main/java/org/parasol/ai/EmailService.java`
+`src/main/java/org/parasol/ai/EmailService.java`
 
 Now, change the current prompt to the one we created together in the previous section.
 
 *Before:*
 
 image::prompt/email-branch-before.png[LangChain4j Email Service Before Functionality Expansion]
 
-Replace the text in the red rectangle with the folowing revised system prompt.
+Replace the text in the red rectangle with the following revised system prompt.
 
 [.console-input]
 [source,text,subs="+attributes,macros+"]
@@ -621,13 +619,13 @@ Assuming your Quarkus environment is still running from the prior steps, the upd
 
 - Reload the Email generate page. It take 10 - 20 seconds to recompile and apply the new prompt in the Quarkus dev mode.
 - Copy and paste the new claim #1 example from the prior section into the form.
-- Click on `Submit`. 
+- Click on `Submit`.
 
 image::prompt/new-email-generate-basic.png[New Generate Email Response]
 
 Now, you'll notice that this does not look drastically different from before the enhancement.  Let's now add the Forward-To Email Address to the form.
 
-Open the `parasol-insurance/app/src/main/webui/src/app/components/EmailGenerate/EmailGenerate.tsx` typescirpt file for the Generate Email view.
+Open the `src/main/webui/src/app/components/EmailGenerate/EmailGenerate.tsx` typescript file for the Generate Email view.
 
 At the top of the source file there is a data structured called EmailResponse.  Add `address` of type `string` to the end of the list.
 
@@ -653,7 +651,7 @@ image::prompt/email_response_addresse.png[email_response_addresse]
 
 Additionally, we must add the address field to the REST Service's JSON Response.
 
-Open the `parasol-insurance/app/src/main/java/org/parasol/model/EmailResponse.java` file to `replace` the constructor with the following code.
+Open the `src/main/java/org/parasol/model/EmailResponse.java` file to `replace` the constructor with the following code.
 
 [.console-input]
 [source,java,subs="+attributes,macros+"]
@@ -663,7 +661,7 @@ public record EmailResponse(String subject, String message, String address) { }
 
 image::prompt/new-field-added-to-email-response.png[Add "address" field to EmailResponse Record]
 
-Now let's revisit the web form and test out the new AI-generated attribute:
+Now let's revisit the https://parasol-app-{user}-dev-parasol-app-{user}-dev.{openshift_cluster_ingress_domain}[web form^] and test out the new AI-generated attribute:
 
 - Reload the Email generate page. It take 10 - 20 seconds to recompile and apply the new prompt in the Quarkus dev mode.
 - Copy and paste the new claim #1 example from the prior section into the form.

content/modules/ROOT/pages/partial-devhub-pre-req.adoc

@@ -61,7 +61,7 @@ Follow the next steps to create a component based on the pre-defined Software Te
 ==== Provide Information for Application
 
 * *Name*: The name of the component. Replace the *Name* with the following domain:
-ß
+
 [.console-input]
 [source,bash,subs="attributes"]
 ----