.github/README.md

Gem - Your Shopping Agent

Gem is an intelligent, friendly, and personalized AI shopping agent designed to help you find the perfect products on Amazon. Engage in a natural conversation, and Gem will guide you through the shopping process with smart recommendations, advanced filtering, and a personalized touch.

This project is built using the Agno framework, which provides a production-ready runtime called AgentOS to manage and serve the AI agent securely.

Frontend UI

This repository contains the backend service for the Gem Agent. The official chat interface for interacting with the agent is available in a separate repository.

➡️ GemAI Frontend Repository

Features

• Conversational Search: Simply chat with Gem about what you're looking for. No more rigid keyword searches.
• Visual Search: Upload images and let Gem find similar products on Amazon.
• Advanced Filtering: Effortlessly narrow down results by price range, category, ratings, best-sellers, and active deals.
• Intelligent Reranking: Uses Cohere's state-of-the-art reranking model to sort products based on true relevance to your query, not just keywords.
• Personalized Experience: Gem remembers your preferences across conversations, providing a tailored shopping journey every time.
• Secure & Scalable: Built on AgentOS, which runs as a secure FastAPI application within your own infrastructure.
• Dockerized: Fully containerized for easy, consistent, and reproducible deployment anywhere.

How It Works

The agent follows a sophisticated workflow to deliver highly relevant product recommendations:

1. User Interaction: A user sends a request (e.g., "I need running shoes under $100") from the frontend to the secure AgentOS API endpoint.
2. Agent Processing: The request is routed to the shopping-agent, which is powered by Google Gemini. The agent analyzes the user's intent based on its core instructions (app/prompts.py).
3. Tool Execution: The agent identifies the need to search for products and calls the fetch_products tool.
4. Product Search: The tool queries a RapidAPI Amazon Search endpoint to retrieve a list of candidate products.
5. Relevance Reranking: The initial results are passed to the Cohere Rerank model. This step is crucial, as it re-orders the products to prioritize those that are most semantically relevant to the user's specific query.
6. Memory & Context: The agent uses a Groq-powered Memory Manager with a Redis backend to recall user preferences (e.g., "user prefers Nike") and maintain conversation history.
7. Response Generation: The Gemini model synthesizes the reranked product data and its memory to generate a friendly, conversational response, highlighting the best options and asking clarifying questions.

Tech Stack

• Framework: Agno
• Core LLM: Google Gemini (gemini-2.5-flash)
• Memory Manager LLM: Groq (openai/gpt-oss-120b)
• Reranking Model: Cohere (rerank-v3.5)
• Backend Server: FastAPI (via AgentOS)
• Database: Redis (for session history and agentic memory)
• Containerization: Docker
• Product Search API: Amazon Search via RapidAPI