Update README.md

README.md

@@ -1,13 +1,349 @@
 ---
-title: HopePet
-emoji: 🐨
-colorFrom: gray
-colorTo: blue
-sdk: gradio
-sdk_version: 6.17.3
-python_version: '3.13'
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+language:
+- en
+license: mit
+library_name: transformers
+tags:
+- pet-care
+- ai-assistant
+- recommendation-system
+- embeddings
+- text-generation
+- synthetic-data
+- gradio
+- huggingface
+datasets:
+- synthetic-pet-care-dataset
+metrics:
+- top_3_retrieval_hit_rate
+- top_5_retrieval_hit_rate
+---
+
+# 🐾 HOPEPET AI: Pet Care Recommendation & Generation Assistant
+### Final AI Application Project | Reichman University
+**Authors:** Shaked & Maya
+
+---
+
+## Project Overview
+
+HOPEPET is an AI-powered pet-care assistant for dog and cat owners. The app helps users describe a pet-related problem and receive responsible first-step guidance based on similar synthetic pet-care cases.
+
+The motivation behind the project is simple: pet owners often do not know how serious a situation is. A symptom that looks mild in one pet may be more serious in another pet depending on age, medical background, appetite, energy level, pain signs, emergency signs, and symptom duration.
+
+For example, a dog shaking during fireworks may be related to anxiety, while a senior cat that suddenly stops eating may require veterinary attention. HOPEPET does not diagnose animals. Instead, it retrieves similar cases and generates a clear, safety-focused first response.
+
+> **Safety note:** HOPEPET provides general guidance only and does not replace professional veterinary advice. If a pet has difficulty breathing, seizures, bleeding, possible poisoning, repeated vomiting, severe weakness, collapse, or cannot stand, the user should contact a veterinarian or emergency clinic immediately.
+
+---
+
+## Application Logic
+
+The app combines retrieval and generation. First, it finds similar cases using embeddings. Then, it uses a Hugging Face generative model to create one final response for the user.
+
+```text
+User question
+→ Text embedding
+→ Similarity search
+→ Top 3 similar pet-care cases
+→ Hugging Face generation model
+→ Final AI response
+```
+
+The final output includes the problem category, estimated urgency level, recommended next step, safe first steps, veterinary warning, similar cases from the dataset, and one generated answer.
+
+---
+
+## Dataset Overview
+
+The project uses a synthetic pet-care dataset with **10,000 examples**. Each row represents one possible pet-care case for a dog or cat.
+
+| Dataset Element | Description |
+|---|---|
+| Dataset type | Synthetic text dataset |
+| Number of examples | 10,000 |
+| Domain | Pet care |
+| Supported pets | Dogs and cats |
+| Main AI task | Recommendation + Generation |
+| Main retrieval field | `retrieval_text` |
+| Final output | User-facing pet-care guidance |
+
+The dataset includes structured fields such as pet type, age group, medical background, symptoms, urgency level, safe first steps, recommended next step, and veterinary warning.
+
+A key column is `retrieval_text`. This column combines the most important details of each case into one searchable text field, which is later converted into embeddings.
+
+---
+
+## Synthetic Data Generation
+
+The dataset was generated synthetically to support a full AI application. The generation process was not based on one simple prompt. It used several prompting techniques to create a structured, diverse, and safety-aware dataset.
+
+| Prompting Technique | Purpose |
+|---|---|
+| Role-based prompting | The model acted as a dataset creator for a responsible pet-care assistant. |
+| Constraint-based prompting | The data followed a strict schema with required columns and controlled categories. |
+| Variation prompting | The dataset includes different pets, symptoms, ages, urgency levels, and medical backgrounds. |
+| Safety-focused prompting | The cases include emergency signs, vet warnings, and safe next steps. |
+| Retrieval-focused prompting | The `retrieval_text` column was created for embedding-based search. |
+
+This structure makes the dataset useful for both recommendation and generation.
+
+---
+
+## Data Validation and Cleaning
+
+Before building the AI system, the dataset was validated to make sure it was clean and consistent. The checks included dataset shape, column names, data types, missing values, duplicate rows, unique values, text length fields, and categorical consistency.
+
+![Data Quality Checks](hopepet_readme_assets/01_step_3_data_quality_checks.png)
+
+![Additional Data Quality Checks](hopepet_readme_assets/02_step_3_data_quality_checks.png)
+
+The final dataset contains no missing values and no duplicate rows after cleaning. This matters because both recommendation and generation depend on clean, consistent examples.
+
+---
+
+## Descriptive Statistics
+
+The descriptive statistics section helped verify that the dataset values are reasonable before moving to embeddings and generation.
+
+The main numeric fields are `pet_age_years`, `user_question_word_count`, `retrieval_text_word_count`, and `detailed_advice_word_count`. The main categorical fields are `pet_type`, `pet_age_group`, `problem_category`, `urgency_level`, `medical_background`, and `recommended_next_step`.
+
+![Outlier Detection](hopepet_readme_assets/03_outlier_detection_handling.png)
+
+![Outlier Handling](hopepet_readme_assets/04_outlier_detection_handling.png)
+
+The numeric analysis showed that pet ages are within a realistic range for dogs and cats. The text-length fields also showed an important pattern: `retrieval_text` is longer than `user_question`, because it contains richer context for semantic search.
+
+![Categorical Statistics Summary](hopepet_readme_assets/05_2_categorical_statistics_summary.png)
+
+The categorical summary shows that the dataset combines controlled categories with meaningful variety. This is useful because the app needs structure, but it also needs enough diversity to retrieve relevant cases.
+
+---
+
+## Exploratory Data Analysis
+
+The EDA helped understand what the dataset contains and whether it behaves in a logical way.
+
+### Pet Type Distribution
+
+![Distribution of Pet Types](hopepet_readme_assets/06_1_distribution_of_pet_types.png)
+
+The dataset is almost balanced between dogs and cats. This is important because HOPEPET should support both dog owners and cat owners, without being strongly biased toward only one pet type.
+
+### Pet Age Groups
+
+![Distribution of Pet Age Groups](hopepet_readme_assets/07_2_distribution_of_pet_age_groups.png)
+
+The dataset includes puppies, kittens, adult pets, and senior pets. Age matters because the same symptom can have a different urgency depending on the pet’s life stage.
+
+### Problem Categories
+
+![Distribution of Problem Categories](hopepet_readme_assets/08_3_distribution_of_problem_categories.png)
+
+The dataset covers several pet-care areas, including health, emergency, anxiety, behavior, training, nutrition, and grooming. This variety makes the app more useful because users may come with many different types of questions.
+
+### Urgency Levels
+
+![Distribution of Urgency Levels](hopepet_readme_assets/09_4_distribution_of_urgency_levels.png)
+
+The dataset includes Low, Medium, High, and Emergency urgency levels. This allows the system to provide different levels of guidance depending on the seriousness of the case.
+
+### Medical Background
+
+![Top 10 Medical Background Categories](hopepet_readme_assets/10_5_top_10_medical_background_categories.png)
+
+Medical background is important because the same symptom may require different guidance for a healthy pet and for a pet with an existing condition.
+
+---
+
+## Safety and Consistency Analysis
+
+This part checks whether the synthetic dataset follows responsible logic between symptoms, urgency levels, and recommended actions.
+
+### Problem Category vs. Urgency Level
+
+![Problem Category vs Urgency Level](hopepet_readme_assets/11_1_problem_category_vs_urgency_level.png)
+
+This heatmap shows how urgency levels are distributed within each problem category. Emergency cases are strongly connected to Emergency urgency. Health-related cases tend to have higher urgency. Training, grooming, and nutrition cases are more often connected to Low or Medium urgency. This supports the internal logic of the dataset.
+
+### Age Group and Urgency
+
+![Pet Age Group and Urgency Level Bubble Chart](hopepet_readme_assets/12_2_pet_age_group_and_urgency_level_bubble_chart.png)
+
+This bubble chart shows that all age groups are represented across urgency levels. This matters because the recommendation system should work for puppies, kittens, adult pets, and senior pets.
+
+### Emergency Signs and Urgency
+
+![Emergency Signs and Urgency Distribution](hopepet_readme_assets/13_3_emergency_signs_and_urgency_distribution.png)
+
+This is one of the most important safety checks. Cases with emergency signs are connected to Emergency urgency. This supports the idea that HOPEPET should treat emergency signs as high-risk and recommend immediate veterinary attention.
+
+### Recommended Next Step by Urgency
+
+![Recommended Next Step by Urgency Level](hopepet_readme_assets/14_4_recommended_next_step_by_urgency_level.png)
+
+This heatmap checks whether the recommended next step matches the urgency level.
+
+| Urgency Level | Expected Recommendation |
+|---|---|
+| Low | Monitor at home |
+| Medium | Monitor closely |
+| High | Contact a veterinarian soon |
+| Emergency | Contact an emergency veterinary clinic immediately |
+
+The graph confirms that the dataset provides consistent and safety-focused next steps.
+
+### High-Risk Cases by Medical Background
+
+![High-Risk Cases by Medical Background](hopepet_readme_assets/15_5_high_risk_cases_by_medical_background.png)
+
+This graph shows the percentage of High or Emergency cases within each medical background. It highlights why medical history is important: the same symptom may require more careful attention for pets with existing conditions.
+
+### Recommended Next Step by Problem Category
+
+![Recommended Next Step by Problem Category](hopepet_readme_assets/16_6_recommended_next_step_by_problem_category.png)
+
+This graph shows that different problem categories lead to different recommended actions. The system does not give one generic answer for every case. It adjusts the next step according to the type and seriousness of the problem.
+
+### Appetite, Energy, and Risk
+
+![High-Risk Rate by Appetite Status and Energy Level](hopepet_readme_assets/17_6_high_risk_rate_by_appetite_status_and_energy_level.png)
+
+This graph looks at the relationship between appetite, energy level, and high-risk cases. A pet that is not eating and has low energy is usually more concerning than a pet with normal appetite and normal energy.
+
+### Recent Change and Risk
+
+![Risk Lift by Recent Change](hopepet_readme_assets/18_7_risk_lift_by_recent_change.png)
+
+This graph checks whether recent changes are connected to a higher or lower risk rate. Recent changes can be important context because a sudden change in behavior, appetite, or environment may affect the urgency of the situation.
+
+---
+
+## Recommendation with Embeddings
+
+The recommendation component uses text embeddings. Each `retrieval_text` is converted into a vector. The user input is also converted into a vector. Then the system compares the user vector to all dataset vectors using cosine similarity and returns the top 3 most similar cases.
+
+This is useful because the system can find cases that are similar in meaning, not only cases that use the exact same words.
+
+```text
+"My dog is shaking and hiding during fireworks"
+```
+
+can be semantically similar to:
+
+```text
+"Dog is anxious because of loud noises"
+```
+
+even if the wording is different.
+
+### Tested Embedding Models
+
+I tested three Hugging Face embedding models:
+
+| Model | Embedding Dimension | Runtime Seconds | Top 3 Hit Rate | Top 5 Hit Rate |
+|---|---:|---:|---:|---:|
+| all-MiniLM-L6-v2 | 384 | 100.03 | 1.00 | 1.00 |
+| paraphrase-MiniLM-L3-v2 | 384 | 25.77 | 0.83 | 1.00 |
+| all-mpnet-base-v2 | 768 | 610.24 | 1.00 | 1.00 |
+
+The score is a retrieval hit rate, not regular classification accuracy. A Top 3 hit means that the expected problem category appeared somewhere within the top 3 retrieved cases.
+
+### Selected Model
+
+The selected embedding 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.
+
+Although `all-mpnet-base-v2` also performed well, it was much slower and produced larger embeddings. Although `paraphrase-MiniLM-L3-v2` was faster, it had lower Top 3 retrieval performance.
+
+The final embedding matrix shape is:
+
+```text
+(10000, 384)
+```
+
+This means that all 10,000 pet-care cases were converted into 384-dimensional vectors.
+
+---
+
+## Generation Component
+
+HOPEPET also includes a Generative AI component using a Hugging Face model.
+
+The generation model receives the user question, the top 3 retrieved similar cases, problem category, urgency level, triage reason, safe first steps, recommended next step, and veterinary warning. Then it generates one final user-facing response.
+
+The response is designed to be clear, helpful, responsible, safety-focused, based on retrieved cases, and not a medical diagnosis.
+
+### Example User Flow
+
+User input:
+
+```text
+My senior cat stopped eating today and seems very tired.
+```
+
+Expected system behavior:
+
+- Retrieve similar cases related to cats, appetite loss, tiredness, health or nutrition concerns, and higher urgency.
+- Generate a response that explains the main concern.
+- Include the estimated urgency level.
+- Recommend the next step.
+- Add a veterinary warning and safety disclaimer.
+
+---
+
+## Final Gradio App
+
+The final application is built with Gradio. The app displays the user input, top 3 similar cases, problem category, urgency level, recommended next step, generated AI response, veterinary warning, and safety disclaimer.
+
+### Quick Starter Examples
+
+```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 three different situations: anxiety, health concern, and training.
+
+---
+
+## Technologies Used
+
+- Python
+- Pandas
+- NumPy
+- Matplotlib
+- Scikit-learn
+- Sentence Transformers
+- Hugging Face Transformers
+- Hugging Face Models
+- Gradio
+- Google Colab
+
+---
+
+## Limitations and Future Improvements
+
+This project uses a synthetic dataset, so it does not replace real veterinary data. The app does not diagnose medical conditions and does not replace a veterinarian. The generated response depends on the quality of the retrieved similar cases, and real-world deployment would require expert veterinary review and stronger safety validation.
+
+Future improvements could include real anonymized veterinary guidance data, more pet types, multilingual support, stronger emergency detection, structured user forms, user feedback, and a larger embedding evaluation set.
+
+---
+
+## Conclusion
+
+HOPEPET demonstrates a complete AI application pipeline for responsible pet-care guidance.
+
+The project includes synthetic data generation, data validation, EDA, 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.