README.md

metadata

title: HopePet
emoji: 🐾
colorFrom: pink
colorTo: blue
sdk: gradio
app_file: app.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:

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:

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

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.

---

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:

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.

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.

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.

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.

---

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

.

---

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.

---

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.

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.

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.

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.

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.

---

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.

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.

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.

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.

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.

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.

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.

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.

---

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:

My dog is shaking and hiding during fireworks.

can be semantically similar to:

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

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:

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:

(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.

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.

---

Part 8 — Generation Component

HOPEPET includes a text generation component using a Hugging Face model:

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.

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:

user input → embedding retrieval → similar cases → generated response → safety disclaimer

Quick Starter Examples

The app includes example prompts such as:

My dog is shaking and hiding during fireworks.

My senior cat stopped eating today and seems very tired.

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.