New documentation using mkdocs (#601)

Set up documentation site with Material for MkDocs

.github/404.md

@@ -0,0 +1,7 @@
+---
+permalink: /404.html
+---
+
+# Retail Demo Store 
+
+Read the documentation live [here](/retail-demo-store/)

.github/workflows/build-ui.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - master
+    paths-ignore:
+      - 'docs/**'
 jobs:
   build:
     runs-on: ubuntu-latest

.github/workflows/mkdocs.yml

@@ -0,0 +1,28 @@
+name: mkdocs
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocs-nav-weight
+      - run: mkdocs gh-deploy --force

.github/workflows/ruff.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - master
+    paths-ignore:
+      - 'docs/**'
 jobs:
   ruff:
     runs-on: ubuntu-latest

.gitignore

@@ -41,4 +41,5 @@ workshop/requirements.txt
 workshop/1-Personalization/generate_interactions_personalize.py
 workshop/1-Personalization/generate_interactions_personalize_offers.py
 dist
-*.code-workspace
+*.code-workspace
+datasets/1.4/images/*

aws/cloudformation-templates/base/opensearch.yaml

@@ -14,6 +14,7 @@ Parameters:
 
 Resources:
 
+
   OpenSearchDomain:
     Type: AWS::OpenSearchService::Domain
     Properties:

docs/Available Demos/GenAI Personalized Product Descriptions.md

@@ -0,0 +1,49 @@
+---
+weight: 7
+---
+# Personalized Product Descriptions with GenAI
+
+## Overview
+
+Generative AI can be used to automate the creation of marketing content, including generating personalized product descriptions. This can save marketers significant time and effort, allowing them to focus on other aspects of their strategy.
+
+The real power of generative AI for product descriptions is the ability to dynamically create unique, personalized content for each customer segment or individual user. Previously, marketers would need to manually generate multiple copies of product descriptions for different customer attributes. Generative AI can automate this process, providing opportunities to tailor the descriptions to each user's preferences and context.
+
+## Implementation in the Retail Demo Store
+
+The Retail Demo Store integrates the product service with Amazon Bedrock to retrieve personalized product descriptions based on the logged-in user's age and interests.
+
+Amazon Bedrock makes Foundation Models (FMs) accessible via an API, and in this demo, Anthropic's Claude v2 is the underlying FM used for generating the personalized descriptions.
+
+The prompt used to generate the personalized descriptions takes the following form:
+
+```
+I'd like you to rewrite the following paragraph using the following instructions:
+"{instructions}"
+
+"{original product description}"
+
+Please put your rewrite in <p></p> tags.
+```
+
+The instructions used are:
+
+```
+Please generate an enhanced product description personalised for a customer aged {age range}, interested in {interests}.
+However, do not mention their age in the rewrite. 
+The product is named "{product name}" and is a product of type "{product type}" in the {product category} category.
+```
+
+This allows the generative AI model to dynamically create a personalized product description based on the user's age and interests, without explicitly mentioning those details.
+
+## Architecture
+
+The overall architecture of this demo involves the following components:
+
+1. The user authenticates with Amazon Cognito and obtains an identity token, which is passed to subsequent API requests.
+2. The Web UI uploads a product image to S3 and calls the API Gateway to request a personalized product description.
+3. The API Gateway validates the identity token and proxies the request to a Lambda function.
+4. The Lambda function retrieves the user's age and interests from the identity token, constructs the prompt, and calls Amazon Bedrock to generate the personalized description.
+5. The generated description is returned to the Web UI for display.
+
+By integrating Generative AI through Amazon Bedrock, the Retail Demo Store is able to provide personalized product descriptions that are tailored to each individual user, improving the overall shopping experience.

docs/Available Demos/Geofencing and Location-aware Personalization.md

@@ -0,0 +1,40 @@
+---
+weight: 30
+---
+## Geofencing and Location-aware Personalization
+
+The Retail Demo Store integrates Amazon Location Services to demonstrate how businesses can leverage location data to deliver personalized experiences and increase foot traffic to physical stores.
+
+### Use Case
+
+Imagine a customer is out shopping and approaches one of your retail locations. As they get closer, you want to be able to detect their presence, deliver a personalized offer or notification, and potentially encourage them to come into the store to redeem the offer or pick up an online order.
+
+![image](../assets/geolocation.png)
+
+### How it Works
+
+The Retail Demo Store uses Amazon Location Services to set up a geofence around a sample physical store location. As customers approach the store, their location is detected, and personalized messages are delivered to them through Amazon Pinpoint.
+
+The key components are:
+
+1. **Location Service**: Defines the geofence around the physical store and tracks customer proximity.
+2. **Offers Service**: Maintains a catalog of personalized offers that can be triggered based on customer location.
+3. **Pinpoint**: Sends personalized push notifications, SMS, or email messages to customers when they enter the geofence.
+4. **Personalize**: Integrates with Amazon Personalize to select the most relevant offer for each customer based on their profile and past behaviors.
+
+When a customer enters the geofence, the following happens:
+
+1. The Location Service detects the customer's proximity to the store.
+2. The Offers Service selects a personalized offer for the customer using Amazon Personalize.
+3. Pinpoint delivers the personalized offer to the customer via their preferred communication channel (e.g., push notification, SMS, email).
+4. The customer can then redeem the offer by visiting the store.
+
+### Benefits
+
+- **Increased Foot Traffic**: Personalized offers and notifications encourage customers to visit the physical store.
+- **Improved Customer Experience**: Customers receive timely, relevant offers based on their location and preferences.
+- **Enhanced Omni-Channel Strategy**: Integrating location data with other customer data (e.g., purchase history, browsing behavior) enables a more comprehensive, personalized customer experience across digital and physical channels.
+
+### Try it Yourself
+
+To experience the Geofencing and Location-aware Personalization demo, deploy the Retail Demo Store and navigate to the "In Store View -> Location Geofence" section. You can then simulate a customer approaching the store and see the personalized offer delivered.

docs/Available Demos/Messaging and Engagement.md

@@ -0,0 +1,28 @@
+---
+weight: 20
+---
+# Messaging and Engagement
+
+The Retail Demo Store integrates Amazon Pinpoint and Amazon Personalize to provide a seamless omni-channel personalization experience for the customer.
+
+## Welcome Emails
+
+When a new user signs up for a Retail Demo Store account, Amazon Pinpoint is used to automatically send a welcome email. The email content is personalized based on the user's profile information, such as their name, and can include personalized product recommendations generated by Amazon Personalize.
+
+## Abandoned Cart Emails
+
+If a user adds items to their cart but does not complete the purchase, Amazon Pinpoint is used to send an "abandoned cart" email. This email includes a coupon code to incentivize the user to return and complete their purchase. The product recommendations in the email are personalized based on the user's browsing and purchase history.
+
+## SMS Alerts and Offers
+
+The Retail Demo Store also integrates SMS messaging powered by Amazon Pinpoint. Users can opt-in to receive text alerts, such as notifications when they are near a physical store location. These alerts can include personalized product offers generated by Amazon Personalize.
+
+## Omni-Channel Personalization
+
+By connecting Amazon Pinpoint with Amazon Personalize, the Retail Demo Store is able to create a unified, omni-channel personalization experience. All customer interactions, whether on the website, in emails, or through SMS, are fed into the Personalize machine learning models. This allows the recommendations and offers to be consistently personalized across every touchpoint.
+
+## Real-Time Segmentation
+
+Amazon Pinpoint enables the creation of real-time user segments based on the customer's behavior across web, mobile, email, and SMS channels. These dynamic segments can then be used to trigger personalized messaging campaigns through the channel most appropriate for each user.
+
+Overall, the Messaging and Engagement demo showcases how retailers can leverage the power of Amazon Pinpoint and Amazon Personalize to deliver a highly personalized, omni-channel customer experience that drives engagement and conversion.

docs/Available Demos/Personalization.md

@@ -0,0 +1,31 @@
+---
+weight: 10
+---
+# Personalization
+
+The Retail Demo Store showcases several personalization capabilities powered by Amazon Personalize, a machine learning service that makes it easy to add sophisticated personalization to applications. The personalization demos in the Retail Demo Store cover the following key use cases:
+
+## Related Items Recommendations
+The product detail pages in the Retail Demo Store include a "Compare similar items" carousel that displays products similar to the one being viewed. This is implemented using the Similar-Items algorithm in Amazon Personalize, which recommends related items based on user behavior (co-occurrence in interactions data) and thematic similarity between products.
+
+The Similar-Items algorithm considers both how often products appear together in user histories, as well as the attributes of the products themselves, to identify items that are truly similar - even for long-tail or new products with limited historical data.
+
+Additionally, the Personalized-Ranking recipe is used to re-order the related items recommendations based on the current user's preferences, providing a personalized experience.
+
+## Recommended for You
+The "Inspired by your shopping trends" section on the homepage displays personalized product recommendations for the current user, using the User-Personalization recipe in Amazon Personalize. This recipe balances recommending items the user is likely to engage with, based on their historical behavior, with exposing them to new and trending products.
+
+The User-Personalization recipe handles the "cold-start" challenge, where limited or no historical information is known about a user or an item, by incorporating user attributes and item metadata to make relevant recommendations.
+
+## User Segmentation
+Amazon Personalize also enables advanced user segmentation, going beyond traditional rules-based approaches. The Item-Affinity and Item-Attribute-Affinity recipes can identify high-propensity user segments for specific products or product categories, without the need to maintain complex business rules.
+
+This allows retailers to efficiently target marketing campaigns, promotions, or merchandising strategies to the users most likely to engage.
+
+## Real-Time Personalization
+The Retail Demo Store showcases how Amazon Personalize can be integrated with the web user interface to deliver real-time personalized experiences. As users interact with the storefront, their clickstream data is captured and sent to Personalize's real-time event tracking. Personalize then uses this data to update the user's profile and deliver personalized recommendations in subsequent page views.
+
+## Measuring Personalization Impact
+The Retail Demo Store also includes workshops that demonstrate how to measure the impact of personalization using techniques like A/B testing, interleaving, and multi-armed bandit experiments. These allow you to rigorously evaluate the effectiveness of your personalization strategies and make data-driven decisions to optimize the customer experience.
+
+Overall, the personalization capabilities showcased in the Retail Demo Store illustrate how Amazon Personalize can be easily integrated to deliver sophisticated, scalable personalization for ecommerce applications - without the need for extensive machine learning expertise.

docs/Available Demos/Product Search.md

@@ -0,0 +1,34 @@
+---
+weight: 60
+---
+# Product search
+
+The Search demo in the Retail Demo Store showcases how to integrate Amazon OpenSearch Service (formerly Amazon Elasticsearch Service) to provide a powerful and customizable search experience for an ecommerce application.
+
+The current demo presents only type-ahead search at the moment, but the principles could be extended to support a fully fledged search solution.
+
+## How it Works
+
+![search](../assets/search.png)
+
+The core components of the Search demo are:
+
+1. **Search Service**: This is a RESTful web service that provides an API for querying the product catalog and returning search results. The service is deployed as a Docker container on Amazon ECS.
+
+2. **OpenSearch Cluster**: Amazon OpenSearch Service is used to host the product index and power the search functionality. When the Retail Demo Store is initially deployed, the product catalog is automatically indexed in OpenSearch.
+
+3. **Web UI Integration**: The Retail Demo Store's web user interface makes calls to the Search Service API when a user performs a search. The search results are then displayed to the user.
+
+Here's a step-by-step breakdown of how the Search demo works:
+
+1. **User Initiates a Search**: A user enters a search query in the Retail Demo Store's web UI.
+2. **Web UI Calls Search Service**: The web UI makes a request to the Search Service API, passing the user's search query.
+3. **Search Service Queries OpenSearch**: The Search Service forwards the query to the OpenSearch cluster and retrieves the relevant product results.
+4. **Search Service rerank the results**: The Search Service send the results to Amazon Personalize to rerank based on the current customer.
+5. **Web UI Displays Results**: The web UI receives the search results and displays them to the user.
+
+
+
+## Conclusion
+
+The Search demo in the Retail Demo Store showcases how to leverage Amazon OpenSearch Service to provide a scalable, customizable, and integrated search experience for an ecommerce application. By combining the power of OpenSearch with the overall architecture of the Retail Demo Store, businesses can deliver a highly engaging and responsive search functionality to their customers.

docs/Available Demos/Room Makeover.md

@@ -0,0 +1,44 @@
+---
+weight: 5
+---
+# Room Makeover: Revolutionizing Interior Design with GenAI
+
+In today's fast-paced world, consumers are constantly seeking new and innovative ways to personalize their living spaces. The Retail Demo Store's Room Makeover demo harnesses the power of cutting-edge AI technologies to enable an unprecedented level of personalization in interior design.
+
+## The Challenge
+
+Traditionally, the process of reimagining a room's décor has been time-consuming and labor-intensive. Homeowners often struggle to visualize how different design elements would look in their existing spaces, leading to hesitation and missed opportunities.
+
+## The Solution
+
+![screenshot1](../assets/room-screenshot.png)
+
+The Room Makeover demo revolutionizes this experience by seamlessly integrating several AWS services to create a truly immersive and personalized interior design solution.
+
+
+1. **User Uploads Room Image**: Customers can upload a photo of their existing room through a secure and intuitive web interface powered by AWS Amplify and Amazon Cognito.
+
+2. **Image Analysis**: The uploaded image is then analyzed using Amazon Rekognition, which detects and identifies the key furniture and decor elements within the room.
+
+3. **Product Matching**: The detected objects are matched against a product catalog using Amazon Bedrock's Titan Multimodal Embeddings model, which provides a rich understanding of product attributes and similarities.
+
+4. **Personalized Prompts**: Combining the detected room elements with the product matches, the demo generates a personalized prompt that can be used to guide the AI-powered room redesign.
+
+5. **Stable Diffusion Generation**: The prompt is then passed to a custom Stable Diffusion model deployed on Amazon SageMaker, which generates a new image depicting the room in the selected design style.
+
+6. **Continuous Optimization**: The generated image is further analyzed to identify additional furniture and decor elements, which are matched back to the product catalog to allow customers to select and purchase straight from the generated room image.
+
+
+## The Benefits
+
+The Room Makeover demo offers several key benefits for businesses and consumers:
+
+1. **Personalization at Scale**: By leveraging the power of AI, the demo can generate personalized room designs for each customer, at scale, rather than relying on manual, labor-intensive processes.
+
+2. **Increased Engagement and Conversion**: The immersive, AI-powered experience helps customers visualize how their spaces could be transformed. The generated product in the image is automatically linked to the product catalog and features a direct "add to basket" functionality, driving increased engagement and ultimately, higher conversion rates. 
+
+3. **Streamlined Workflows**: The automated product matching and prompt generation capabilities reduce the time and effort required by interior design professionals, enabling them to focus on higher-value tasks.
+
+## Conclusion
+
+The Room Makeover demo showcases the transformative potential of AI-powered personalization in the interior design industry. By seamlessly integrating cutting-edge AWS services, businesses can now offer their customers a truly innovative and engaging experience, ultimately driving growth and customer satisfaction.