--- title: HopePet emoji: 🐾 colorFrom: pink colorTo: blue sdk: gradio app_file: app_v2.py python_version: 3.12 sdk_version: 6.19.0 --- # 🐾 HOPEPET AI ## Pet-Care Recommendation & Generation Assistant **Final Project – Intro to Data Science** **Authors:** Shaked & Maya **Hugging Face Space:** https://huggingface.co/spaces/mayadeeb08/HopePet --- ## What This Project Does **HOPEPET AI** is an interactive pet-care assistant for dog and cat owners. A user describes a pet-related concern in natural language, and the system returns a responsible, safety-focused first response. The app does not diagnose animals and does not replace a veterinarian. Instead, it combines: - **Synthetic pet-care data** - **NLP text processing** - **Embedding-based recommendation** - **Cosine similarity retrieval** - **Hugging Face text generation** - **A Gradio user interface** The goal is to help users understand whether a situation may be **low-risk, medium-risk, high-risk, or an emergency**, and to suggest a safe next step. > **Safety disclaimer:** This app provides general guidance only and does not replace professional veterinary advice. If a pet has difficulty breathing, seizures, bleeding, possible poisoning, repeated vomiting, collapse, severe weakness, or cannot stand, the user should contact a veterinarian or emergency clinic immediately. --- ## Example: How the App Works A user enters a free-text pet-care question: ```text My dog is not eating, seems very tired, and has been hiding since yesterday. ``` HOPEPET AI then performs the following steps: 1. Converts the user question into an embedding vector. 2. Compares it with all pet-care cases in the dataset. 3. Retrieves the **top 3 most similar cases** using cosine similarity. 4. Uses the retrieved cases as context for the generation model. 5. Returns a safety-focused response with urgency guidance and a recommended next step. Example output: ```text Urgency level: High Recommended next step: Contact a veterinarian as soon as possible. AI response: Your dog’s reduced appetite, low energy, and hiding behavior may indicate that something is wrong, especially because the symptoms have continued since yesterday. Monitor your dog closely, keep water available, and avoid giving medication without veterinary guidance. Because the symptoms involve both appetite loss and low energy, contacting a veterinarian as soon as possible is recommended. Safety note: This app provides general guidance only and does not replace professional veterinary advice. ``` This example shows how the system combines **semantic retrieval** with **text generation** to produce a practical and responsible pet-care response. --- ## End-to-End AI Pipeline ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/u2fQVTmOkDF-BG2ilPR3S.png) ```text User question → Text embedding → Similarity search → Top 3 similar pet-care cases → Hugging Face generation model → Final safety-focused response ``` The final app returns: - Generated AI response - Top 3 similar retrieved cases - Problem category - Urgency level - Recommended next step - Safe first steps - Veterinary warning - Safety disclaimer --- ## HOPEPET AI Decision Flow The diagram below summarizes the logic behind the system. HOPEPET AI connects a pet-care problem to a problem category, maps it to an urgency level, and then recommends the next step. This flow explains how the dataset supports the app’s recommendation logic: different problem categories can lead to different urgency levels, and the urgency level strongly influences the recommended next step. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/4aZqlFj6w3pSfnEn0KnQ6.png) --- ## Dataset Overview The project uses a synthetic pet-care dataset with **10,000 examples**. Each row represents one fictional dog or cat care case. | Dataset Element | Description | |---|---| | Dataset type | Synthetic text dataset | | Number of examples | 10,000 | | Domain | Pet care | | Supported pets | Dogs and cats | | Main AI task | Semantic recommendation + generation | | Main retrieval field | `retrieval_text` | | Final user output | Safety-focused pet-care guidance | Important columns include: - `pet_type` - `pet_age_years` - `pet_age_group` - `medical_background` - `main_symptom` - `secondary_symptoms` - `emergency_signs` - `problem_category` - `urgency_level` - `recommended_next_step` - `safe_first_steps` - `vet_warning` - `user_question` - `retrieval_text` The `retrieval_text` column is especially important because it combines structured case information into one searchable text field. This field is converted into embeddings and used for semantic similarity search. --- ## Synthetic Data Generation The dataset was created using structured prompting. The prompt included a clear role, required schema, controlled categories, safety rules, and formatting constraints. | Prompting Technique | Purpose | |---|---| | Role-based prompting | The model acted as a careful synthetic data creator for a pet-care AI assistant. | | Constraint-based prompting | Each row had to follow a strict schema with required fields. | | Safety-focused prompting | Emergency signs, vet warnings, and safe recommendations were required. | | Variation prompting | The dataset includes different pets, ages, symptoms, medical backgrounds, and urgency levels. | | Retrieval-focused prompting | The `retrieval_text` field was designed for embedding-based search. | Example prompt structure: ```text You are a careful synthetic data generator for a pet-care AI assistant. Generate realistic but fictional dog and cat care cases. Each case must include pet type, age, symptoms, urgency level, recommended next step, safe first steps, veterinary warning, user question, and retrieval_text. Safety rules: - Do not provide a medical diagnosis. - Emergency signs must lead to Emergency urgency. - The response must recommend contacting a veterinarian when needed. - The dataset must not include real personal information. Return the output as structured CSV-style rows. ``` This makes the dataset useful for both **exploratory data analysis** and **AI application development**. --- ## Key Findings from the Data Analysis The exploratory data analysis showed that the dataset is structured, consistent, and suitable for the final recommendation and generation pipeline. Main findings: - The dataset contains **10,000 synthetic pet-care cases** with structured fields for symptoms, urgency, recommendations, and safety guidance. - Missing values appear mainly in optional symptom-related fields, such as emergency signs, pain signs, and secondary symptoms. - Pet types are balanced between dogs and cats. - The dataset includes multiple problem categories, including health, emergency, behavior, anxiety, nutrition, grooming, and training. - Emergency signs are consistently connected to `Emergency` urgency. - Recommended next steps follow a clear safety logic based on urgency level. - Medical background, appetite status, energy level, and recent changes are meaningful factors for understanding risk. - User questions contain meaningful NLP signals such as appetite, energy, tiredness, hiding, eating behavior, and symptom duration. These findings support the use of embeddings and semantic similarity search because the text fields contain meaningful information that can help retrieve relevant pet-care cases. --- # Part 1 — Data Quality and Cleaning Before building the AI system, the dataset was checked for quality, structure, missing values, duplicates, outliers, and consistency. ## Data Quality Checks The initial quality checks confirm that the dataset contains the expected project structure. These checks are important because the recommendation and generation components depend on clean and reliable input data. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/2ZUYwJLxjud3G6wElEdv6.png) ## Missing Values Handling Some symptom-related fields are optional, such as `emergency_signs`, `pain_signs`, and `secondary_symptoms`. Missing values in these columns do not always indicate an error; they often mean that no such signs were reported. Therefore, missing values were replaced with explicit text values such as `No emergency signs reported`, `No pain signs reported`, and `No secondary symptoms reported`. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/RYmVjTdHdQZjZbs0yGVsV.png) ## Age Outlier Detection The age outlier check verifies that pet ages are realistic. The dataset did not include unrealistic values such as negative ages or extremely old pet ages. This matters because pet age can affect urgency and recommendation logic. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/0J90Xsb7QCVUdepgad9qS.png) ## Text Length Outlier Detection Text length was checked for both `user_question` and `retrieval_text`. The `retrieval_text` field is longer because it contains structured case context for semantic search. The detected length outliers were not removed because the examples still contained meaningful pet-care information. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/Nt6butxK89x0NyOMdEpeB.png) --- # Part 2 — NLP Text Exploration ## Most Common Meaningful Words in User Questions The word frequency analysis shows that many user questions focus on important pet-care signals such as appetite, energy level, tiredness, hiding, eating behavior, appetite loss, and restlessness. The graph also includes time-related words such as `days`, `hours`, and `weeks`, which shows that symptom duration is an important part of how users describe a pet-care problem. This supports the decision to use NLP embeddings because the user questions contain meaningful symptom-related language ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/5Ih2mhg0GODyqXyTJuQAD.png) . --- # Part 3 — Descriptive Statistics and Dataset Structure ## Categorical Statistics Summary The categorical summary shows that the dataset includes controlled categories with meaningful variety. This structure is useful because the app needs both consistency and diversity: consistency for safe recommendations, and diversity for retrieving relevant similar cases. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/A6HSAIGDbFLKxZ4YOpXrr.png) --- # Part 4 — Exploratory Data Analysis ## Pet Type Distribution The dataset is balanced between dogs and cats. This helps ensure that the app supports both dog owners and cat owners. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/EQ7SKOidHj_7-fuVYKeJ5.png) ## Pet Age Group Distribution The dataset includes different age groups such as puppies, kittens, adult pets, and senior pets. Age is important because the same symptom can have a different urgency depending on the pet's life stage. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/4nLc4igCmnGRpfX1Bim_D.png) ## Problem Category Distribution The dataset covers several pet-care areas, including health, emergency, anxiety, behavior, training, nutrition, and grooming. This variety allows HOPEPET to respond to different types of user questions. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/7ddaZGLDOvyR4i9TTPvaj.png) ## Urgency Level Distribution The dataset includes four urgency levels: `Low`, `Medium`, `High`, and `Emergency`. This allows the system to provide different guidance depending on the seriousness of the case. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/BBZvWCDkOECfcCCJkIX1B.png) ## Top Medical Background Categories Medical background is an important contextual feature. The same symptom may require different guidance for a healthy pet and for a pet with an existing medical condition. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/zRqLyg9cfmYX2jkqFKerN.png) --- # Part 5 — Relationship and Safety Consistency Analysis This section checks whether the synthetic dataset follows responsible safety logic between symptoms, urgency levels, and recommended next steps. ## Problem Category vs. Urgency Level This heatmap shows how urgency levels are distributed across problem categories. Emergency cases are strongly connected to Emergency urgency, while training, grooming, and nutrition cases tend to appear more often in Low or Medium urgency. This supports the internal logic of the dataset. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/D4d5c5JBhl3xjT0yJA25_.png) ## Pet Age Group and Urgency Level This bubble chart shows how urgency levels are distributed across age groups. It confirms that the dataset includes different urgency levels for puppies, kittens, adult pets, and senior pets. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/jupy3fnX3tLt2XYcPw228.png) ## Emergency Signs and Urgency Distribution This is one of the most important safety checks. Cases with emergency signs are classified as `Emergency`, which shows that the dataset treats emergency symptoms as high-risk situations that require immediate veterinary attention. Cases without emergency signs are distributed across `Low`, `Medium`, and `High`, but not `Emergency`. This makes sense because some cases can still be high-risk due to age, medical background, appetite loss, low energy, or symptom duration, even if no explicit emergency signs are reported. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/jakgmWnHDWGhyVOwOcOTk.png) ## Recommended Next Step by Urgency Level This graph checks whether the recommended next step matches the urgency level. | Urgency Level | Expected Recommendation Logic | |---|---| | Low | Monitor at home and use general care guidance | | Medium | Monitor closely and contact a vet if symptoms continue or worsen | | High | Contact a veterinarian as soon as possible | | Emergency | Contact an emergency veterinary clinic immediately | The graph confirms that the dataset follows a responsible safety structure. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/iRkaAI1MlyR74CtOOlzMd.png) ## High-Risk Cases by Medical Background This chart shows that some medical backgrounds are associated with a higher percentage of `High` or `Emergency` cases. Conditions such as dental problems, obesity, recent surgery, heart disease, kidney disease, and diabetes have higher-than-average risk rates. This suggests that medical background is an important factor for understanding urgency. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/IG-GesLtNI2FaDYSuIYfN.png) ## Recommended Next Step by Problem Category This graph shows that different problem categories lead to different recommended actions. The system does not give one generic recommendation for every case. Instead, the recommended next step changes according to the type and seriousness of the problem. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/LwXiOjDHpX61reIw_tcns.png) ## High-Risk Rate by Appetite Status and Energy Level This analysis shows the relationship between appetite, energy level, and high-risk cases. A pet with reduced appetite and low energy is usually more concerning than a pet with normal appetite and normal energy. This supports the use of appetite and energy level as important context in the dataset. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/d8CsaZz-SOcMGs5uB8k_S.png) ## Risk Lift by Recent Change This chart shows how each recent-change category differs from the overall high-risk rate. Positive values indicate higher-than-average risk, while negative values indicate lower-than-average risk. Possible toxin exposure, outdoor incidents, and recent surgery are the strongest risk-elevating signals. Changes such as new grooming products, new routine, and recent grooming are associated with lower urgency. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/hXLu9J8glYVviSKvQfm3z.png) --- # Part 6 — Recommendation with Embeddings The recommendation component uses semantic text embeddings. Each `retrieval_text` is converted into a numerical vector. The user question is also converted into a vector. Then, the app compares the user vector to all dataset vectors using cosine similarity and returns the **top 3 most similar pet-care cases**. This is useful because the system can find cases that are similar in meaning, not only cases that use the same words. For example: ```text My dog is shaking and hiding during fireworks. ``` can be semantically similar to: ```text A dog is anxious because of loud noises. ``` Even though the wording is different, the meaning is related. ## Tested Embedding Models Three Hugging Face embedding models were tested: | Model | Embedding Dimension | Runtime Seconds | Top 3 Hit Rate | Top 5 Hit Rate | |---|---:|---:|---:|---:| | `sentence-transformers/all-MiniLM-L6-v2` | 384 | 100.03 | 1.00 | 1.00 | | `sentence-transformers/paraphrase-MiniLM-L3-v2` | 384 | 25.77 | 0.83 | 1.00 | | `sentence-transformers/all-mpnet-base-v2` | 768 | 610.24 | 1.00 | 1.00 | ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/HmegxnJ8682RJKgrvve93.png) The score is a **retrieval hit rate**, not classic classification accuracy. A Top 3 hit means that the expected problem category appeared somewhere within the first 3 retrieved cases. ## Selected Embedding Model The selected model is: ```text sentence-transformers/all-MiniLM-L6-v2 ``` This model was selected because it provided the best balance between retrieval quality, runtime, embedding size, and practical usability for the final Gradio app. The final embedding matrix shape is: ```text (10000, 384) ``` This means that all 10,000 pet-care cases were converted into 384-dimensional vectors. ## Why This Is Not Classic Classification Although the dataset contains labels such as `problem_category` and `urgency_level`, the main task in this project is not classic classification. In a classic classification task, the goal is to train a model to predict one label directly. In HOPEPET, the goal is different: the system retrieves semantically similar cases using embeddings and cosine similarity. The retrieved cases then provide context for the final generated response. Therefore, this project is better described as a **semantic retrieval and recommendation system combined with text generation**, rather than a classic classification model. --- # Part 7 — Embedding Space Visualization ## PCA Visualization of Embeddings PCA was used to project the 384-dimensional embeddings into two dimensions for visualization. This helps inspect whether similar categories show some structure in the embedding space. The visualization shows partial semantic structure, but also overlap between categories. This overlap is expected because many pet-care cases are related across categories. For example, Health, Emergency, and Nutrition cases may share symptoms such as appetite loss or low energy. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/-BEVhu6XKYblt-JtxVaz-.png) ## PCA After Standardization After standardization, PCA was applied again as a robustness check. This gives each embedding dimension equal scale before reducing the data to two dimensions. The PCA visualization is used only for inspection. The final recommendation system still uses the full 384-dimensional embeddings with cosine similarity. ![image](https://cdn-uploads.huggingface.co/production/uploads/69d6633b22cc2532d036e88e/BJUPSvXZKPvMnarlQpA3C.png) --- # Part 8 — Generation Component HOPEPET includes a text generation component using a Hugging Face model: ```text google/flan-t5-base ``` The generation model receives: - The user question - The top 3 retrieved similar cases - Problem category - Urgency level - Recommended next step - Safe first steps - Veterinary warning Then it generates one final user-facing response. The response is designed to be: - Clear - Helpful - Safety-focused - Based on retrieved similar cases - Not a medical diagnosis ## Retrieval-Augmented Generation Logic The generation does not happen alone. It is grounded in retrieved similar cases from the dataset. ```text User input → Similar case recommendation → Prompt construction → Generated response ``` This makes the answer more connected to the dataset and less generic. --- # Part 9 — Final Gradio App The final application was deployed as an interactive Gradio app on Hugging Face Spaces. The app includes: - A free-text user input - Top 3 similar retrieved cases - A generated AI response - Urgency level - Recommended next step - Veterinary warning - A clear safety disclaimer The Gradio app turns the notebook pipeline into an interactive user-facing prototype. Instead of only testing the model inside the notebook, users can enter their own pet-care question and receive a structured AI response. This makes the project more practical because it demonstrates the full AI workflow: ```text user input → embedding retrieval → similar cases → generated response → safety disclaimer ``` ## Quick Starter Examples The app includes example prompts such as: ```text My dog is shaking and hiding during fireworks. ``` ```text My senior cat stopped eating today and seems very tired. ``` ```text My puppy keeps biting my hands during playtime. ``` These examples test different situations: anxiety, health concern, and training behavior. --- # Technologies Used - Python - Google Colab - Pandas - NumPy - Matplotlib - Plotly - Scikit-learn - Sentence Transformers - Hugging Face Transformers - Hugging Face Spaces - Gradio --- # Connection to Course Concepts This project combines several concepts learned throughout the course: | Course Concept | How It Appears in HOPEPET | |---|---| | Data Science Process | Defining a problem, creating a dataset, cleaning data, analyzing it, building an AI system, and presenting results | | EDA | Missing values, duplicates, outliers, distributions, categorical summaries, and relationship analysis | | Feature Engineering | Creating `retrieval_text`, `is_high_risk`, text word counts, normalized age, and safety indicators | | NLP | Working with user questions, text fields, word frequency, embeddings, and generation | | Recommendation Systems | Retrieving the top 3 most similar cases using embeddings and cosine similarity | | Deep Learning | Using pre-trained transformer-based models from Hugging Face | | Generative AI | Generating a final user-facing response based on retrieved similar cases | | Prompt Engineering | Using role instructions, constraints, safety rules, and structured prompts | | Deployment | Building an interactive Gradio app on Hugging Face Spaces | The project does not focus on regression, computer vision, or classic classification because the main task is semantic retrieval and responsible text generation. --- # Limitations and Future Work This project uses synthetic data, so the dataset does not represent real veterinary records or real user cases. The cases were created for educational and development purposes and are not a substitute for professional veterinary knowledge or diagnosis. HOPEPET AI provides general first-step guidance only. It does not replace a veterinarian and should not be used as a medical diagnosis tool. For serious symptoms or emergency signs, the system recommends contacting a veterinarian or an emergency veterinary clinic. Another limitation is that the system depends on the quality and coverage of the synthetic dataset. If the dataset does not include enough examples for a specific condition, the recommendation may be less accurate or less detailed. Future improvements could include: - Testing the system with real anonymized and veterinary-approved examples - Adding more pet types beyond dogs and cats - Expanding the dataset with rare medical and behavioral cases - Improving the generation prompt with stricter safety rules - Adding multilingual support - Adding a stronger emergency detection layer before generation - Evaluating recommendations with expert veterinary feedback - Improving the Gradio interface with clearer result sections --- # Conclusion HOPEPET AI demonstrates a complete AI application pipeline for responsible pet-care guidance. The project includes synthetic data generation, data validation, EDA, NLP analysis, embedding-based recommendation, Hugging Face text generation, and a final user-facing Gradio app. The main value of the project is the connection between retrieval and generation. The recommendation system retrieves similar cases from the dataset, and the generation component turns those cases into a clear, responsible, and safety-focused response for the user. HOPEPET AI is a responsible educational AI prototype, not a replacement for professional veterinary care.