FurryMeals - AI Pet Nutrition Advisor

FurryMeals is a sophisticated AI-powered pet nutrition recommendation system. It leverages a modern React frontend and a Python-based FastAPI backend, integrated with Machine Learning and Large Language Models (LLM) to provide highly tailored pet food recommendations based on a pet's unique profile.

🌟 Key Features

• Semantic NLP Engine: Instead of rigid keyword matching, the system uses natural language processing (SentenceTransformers) to understand the semantic meaning of a pet's profile and match it with the most suitable product ingredients and descriptions.
• AI-Powered Explanations: Integrates with the Groq API (Llama 3.3 70b Versatile) to generate personalized, human-readable explanations detailing why a specific product is recommended for the pet's unique body type, age, and health conditions.
• Comprehensive Pet Profiles: Captures detailed information including animal type (dog/cat), age (puppy/kitten, adult, senior), body type, specific health conditions, dietary preferences (e.g., grain-free), primary protein, and ingredient exclusions.
• Modern User Interface: A responsive, interactive React frontend built with Vite, offering seamless navigation and dynamic form inputs to capture pet details.

🏗️ Architecture

1. Frontend (React + Vite)

• Framework: React 19
• Build Tool: Vite
• Routing: React Router DOM
• Icons: Lucide React
• The frontend provides a polished user experience, collecting the pet's dietary requirements via a comprehensive recommendation form and displaying the results with AI-generated rationales in an elegant grid.

2. Backend (FastAPI + Python)

• Framework: FastAPI (provides a robust REST API)
• CORS: Configured to allow cross-origin requests from the React frontend.
• Data Engine: Pandas and NumPy are used for fast data manipulation of the underlying pet product dataset (cleaned_pet_products_updated.csv).

3. Machine Learning Engine (AdvancedPetProductAdvisor)

• Semantic Search: Uses the HuggingFace sentence-transformers/all-MiniLM-L6-v2 model to generate text embeddings of pet products (product name, category, and ingredients). When a user submits a pet profile, a natural language target profile is generated and embedded. Cosine similarity is then calculated to find the closest matching products.
• LLM Rationale Generation: The top recommendations are sent to the Groq API (using the Llama model) to generate an easy-to-understand rationale for the pet owner.

🚀 Getting Started

Prerequisites

• Python 3.8+
• Node.js 18+
• Groq API Key: You must have a valid Groq API key set in your environment variables to enable the AI explanation feature.

Installation

1. Clone the Repository

   git clone <repository-url>
   cd FurryMeals

2. Set up the Backend

   • Navigate to the project root and ensure a Python virtual environment is set up.
   • Install dependencies:

     pip install -r backend/requirements.txt

   • Create a .env file in the backend/ directory based on .env.example:

     GROQ_API_KEY=your_groq_api_key_here

3. Set up the Frontend

   • Navigate to the frontend directory:

     cd frontend
     npm install

Deployment

Deploy the FastAPI backend and React frontend to your preferred hosting provider. Ensure that the VITE_API_URL environment variable is set on the frontend to point to your backend URL.

Wait a few seconds for the Machine Learning model (all-MiniLM-L6-v2) to load into server memory upon backend startup before requesting recommendations.

🧠 How the Recommendation Engine Works

1. Profile Translation: The user's input (e.g., "Senior Dog, Obese, Joint Issues, Grain-Free, Salmon protein") is translated into a target semantic profile sentence.
2. Vectorization: This sentence is vectorized using the pre-loaded SentenceTransformer model.
3. Similarity Search: The target vector is compared against pre-computed embeddings of thousands of pet food products using Cosine Similarity.
4. Filtering: Hard filters are applied (e.g., filtering out excluded ingredients or incorrect animal types).
5. AI Rationale generation: The top N candidates are parsed by the Groq LLM to generate user-friendly justifications for the recommendations based on the product's actual ingredient list.

📁 Project Structure

FurryMeals/
├── backend/
│   ├── data/                 # Contains the pet product CSV dataset
│   ├── ml_engine/            # The core semantic search and LLM integration logic
│   │   └── advanced_engine.py
│   ├── main.py               # FastAPI server and API endpoints
│   ├── requirements.txt      # Python dependencies
│   └── .env                  # API keys and environment variables
├── frontend/
│   ├── public/               # Static assets
│   ├── src/                  # React components, pages, and styles
│   ├── package.json          # Node.js dependencies
│   └── vite.config.js        # Vite configuration
└── README.md                 # Project documentation

📜 License

This project is proprietary and intended for educational/demonstration purposes.