Retail Chat Agent

An interactive retail assistant compatible with AlloyDB for PostgreSQL, featuring contextual search, brand filtering, and RRF (Reciprocal Rank Fusion) hybrid search.

Credits

Original demo and concept by Paul Ramsey. Modified and enhanced by Jason Massie.

Setup

Prerequisites

• Google Cloud Project with AlloyDB and Vertex AI enabled.
• Python 3.10+
• gcloud CLI installed and authenticated.

Installation

1. Clone the repository:

   git clone git@github.com:jasonmassie01/RetailChatAgent.git
   cd RetailChatAgent

2. Install dependencies:

   pip install -r requirements.txt

3. Set up environment variables: Copy start.sh.example to start.sh and set your DB_PASSWORD.

   cp start.sh.example start.sh
   chmod +x start.sh
   # Edit start.sh with your password

Database Setup

1. Restore Backup: This repository includes a split zip archive backup.zip containing products_backup.csv and inventory_items_backup.csv.

   • Run zip -F backup.zip --out single_backup.zip and then unzip single_backup.zip (or use a tool like 7-Zip) to extract the CSVs.
   • You can load these into your AlloyDB instance using pandas or COPY command if you need to recreate the data.

2. Schema: ensure your AlloyDB database has the vector extension enabled and tables created matching the CSV structure.

Image Setup

The application uses product images.

• If images are stored in Google Cloud Storage (GCS), ensure your environment has access.
• The app handles gs:// URIs by converting them to signed URLs or public HTTP URLs if configured.
• Default public bucket mirror: https://storage.googleapis.com/pr-public-demo-data/alloydb-retail-demo/product-images-branded/

Running the App

./start.sh

Access the app at http://localhost:8501.

Features

• Contextual Search: Remembers previous queries (e.g., "in red") to refine search results.
• Brand Filtering: Automatically extracts brand names using Gemini 2.0 Flash.
• Hybrid Search: Combines vector similarity and full-text search using RRF.
• Reranking: Uses ai.rank (Vertex AI Semantic Ranker) to reorder results.