Update README.md

README.md

@@ -1,13 +1,694 @@
 ---
-title: HopePet
-emoji: 🐨
-colorFrom: gray
+title: HOPEPET AI
+emoji: 🐾
+colorFrom: pink
 colorTo: blue
 sdk: gradio
-sdk_version: 6.17.3
-python_version: '3.13'
+sdk_version: 5.0.0
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🐾 HOPEPET AI  
+## Pet Care Recommendation & Generation Assistant
+
+**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 pet-care cases.
+
+The project combines:
+
+- Synthetic dataset generation  
+- Data validation  
+- Descriptive statistics  
+- Exploratory Data Analysis  
+- Embedding-based recommendation  
+- Hugging Face Generative AI  
+- A complete user-input-to-AI-output pipeline  
+
+> **Important:** HOPEPET provides general guidance only and does not replace professional veterinary advice.
+
+---
+
+# 1. Project Overview
+
+Many pet owners are unsure what to do when their dog or cat shows unusual symptoms, anxiety, appetite changes, behavior problems, or training difficulties.
+
+Searching online can be confusing because the same symptom can have a different urgency level depending on:
+
+- Pet type  
+- Age group  
+- Medical background  
+- Symptom duration  
+- Appetite status  
+- Energy level  
+- Pain signs  
+- Emergency signs  
+
+For example:
+
+- A dog shaking during fireworks may be related to anxiety.  
+- A senior cat that suddenly stops eating may require veterinary attention.  
+- A puppy biting during playtime may be a training issue.  
+- A pet with an existing medical condition may need more careful guidance than a healthy pet.  
+
+HOPEPET helps by retrieving similar pet-care cases and generating one clear, safety-focused response.
+
+---
+
+# 2. Main Objective
+
+The main objective of this project is to build a complete AI application that can:
+
+1. Receive a pet-care question from the user.  
+2. Convert the user input into an embedding vector.  
+3. Compare the user input to the dataset cases.  
+4. Retrieve the top 3 most similar cases.  
+5. Use a Hugging Face generative model to create one final response.  
+6. Provide urgency level, safe first steps, recommended next step, and veterinary warning.  
+
+---
+
+# 3. Full AI Pipeline
+
+The final HOPEPET pipeline is:
+
+**User input → Embedding model → Top 3 similar cases → Hugging Face generation model → Final AI response**
+
+![HOPEPET Full AI Pipeline](hopepet_polished_readme_assets/00_hopepet_pipeline_polished.png)
+
+This pipeline connects recommendation and generation.  
+The recommendation system finds relevant similar cases, and the generation component turns those cases into a clear response for the user.
+
+---
+
+# 4. Dataset Overview
+
+The dataset is a synthetic pet-care dataset with structured and text-based fields.
+
+![Dataset Snapshot](hopepet_polished_readme_assets/00_dataset_snapshot_cards.png)
+
+| Metric | Value |
+|---|---|
+| Project name | HOPEPET |
+| Dataset type | Synthetic text dataset |
+| Number of rows | 10,000 |
+| Domain | Pet care |
+| Supported pets | Dogs and cats |
+| Main AI tasks | Recommendation + Generation |
+| Main retrieval field | `retrieval_text` |
+| Final output | User-facing pet-care guidance |
+
+Each row in the dataset represents one possible pet-care case.
+
+The dataset includes information such as:
+
+- Pet type  
+- Pet age  
+- Pet age group  
+- Medical background  
+- Recent change  
+- Main symptom  
+- Secondary symptoms  
+- Symptom duration  
+- Appetite status  
+- Water intake  
+- Energy level  
+- Pain signs  
+- Emergency signs  
+- Problem category  
+- Urgency level  
+- Recommended next step  
+- Triage reason  
+- Safe first steps  
+- User question  
+- Short recommendation  
+- Detailed advice  
+- Veterinary warning  
+- Keywords  
+- Retrieval text  
+
+---
+
+# 5. Synthetic Data Generation
+
+The dataset was created synthetically for the HOPEPET use case.
+
+The goal was to create a large and diverse dataset that supports both:
+
+1. Similar case recommendation  
+2. AI-generated responses  
+
+The generation process focused on realistic combinations of symptoms, pet types, age groups, medical backgrounds, urgency levels, and recommendations.
+
+## Prompting Techniques Used
+
+The synthetic data generation process used several prompting techniques:
+
+### Role-Based Prompting
+
+The model was asked to act as a dataset creator for a responsible pet-care AI assistant.
+
+### Constraint-Based Prompting
+
+The data had to follow a specific structure with required columns, controlled categories, and safety-focused outputs.
+
+### Variation Prompting
+
+The dataset includes different symptoms, pet ages, medical backgrounds, environments, urgency levels, and user goals.
+
+### Safety-Focused Prompting
+
+The generated cases include emergency signs, veterinary warnings, safe first steps, and responsible recommendations.
+
+### Retrieval-Focused Prompting
+
+A special column called `retrieval_text` was created.  
+This column combines the most important details of each case into one searchable text field for embeddings.
+
+---
+
+# 6. Data Validation and Quality Checks
+
+Before building the AI components, I validated the dataset.
+
+The validation process included:
+
+- Checking dataset shape  
+- Checking column names  
+- Checking data types  
+- Checking missing values  
+- Checking duplicate rows  
+- Checking unique values  
+- Checking categorical consistency  
+- Checking text length fields  
+
+![Data Quality Checks](hopepet_polished_readme_assets/01_step_3_data_quality_checks.png)
+
+The dataset was cleaned and prepared for analysis.  
+After cleaning, the dataset contains no missing values and no duplicate rows.
+
+---
+
+# 7. Descriptive Statistics
+
+## 7.1 Numeric Summary
+
+The main numeric fields are:
+
+- `pet_age_years`  
+- `user_question_word_count`  
+- `retrieval_text_word_count`  
+- `detailed_advice_word_count`  
+
+These fields help check whether the values are reasonable and whether the text fields are suitable for the next stages of the project.
+
+![Outlier Detection](hopepet_polished_readme_assets/03_outlier_detection_handling.png)
+
+The numeric analysis shows that pet ages are within a realistic range for dogs and cats.  
+The text length analysis shows that `retrieval_text` is longer than `user_question`, which is expected because it includes richer structured context.
+
+---
+
+## 7.2 Categorical Summary
+
+The dataset also contains important categorical features.
+
+Examples include:
+
+- `pet_type`  
+- `pet_age_group`  
+- `problem_category`  
+- `urgency_level`  
+- `medical_background`  
+- `recommended_next_step`  
+
+For categorical variables, I checked:
+
+- Number of unique values  
+- Most frequent value  
+- Frequency of the most common value  
+- Percentage of the most common value  
+
+![Categorical Statistics Summary](hopepet_polished_readme_assets/05_2_categorical_statistics_summary.png)
+
+This shows that the dataset includes both controlled categories and meaningful variety.  
+For example, `pet_type` has a small number of values, while `medical_background` includes more diverse medical contexts.
+
+---
+
+# 8. Exploratory Data Analysis
+
+## 8.1 Pet Type Distribution
+
+![Distribution of Pet Types](hopepet_polished_readme_assets/06_1_distribution_of_pet_types.png)
+
+The dataset is almost balanced between dog and cat cases.  
+This is important because the app is designed to support both dog and cat owners.
+
+---
+
+## 8.2 Pet Age Group Distribution
+
+![Distribution of Pet Age Groups](hopepet_polished_readme_assets/07_2_distribution_of_pet_age_groups.png)
+
+The dataset includes all major life stages:
+
+- Puppies  
+- Kittens  
+- Adult pets  
+- Senior pets  
+
+Age is important because the same symptom may have a different urgency level depending on the pet’s life stage.
+
+---
+
+## 8.3 Problem Category Distribution
+
+![Distribution of Problem Categories](hopepet_polished_readme_assets/08_3_distribution_of_problem_categories.png)
+
+The dataset covers several pet-care problem categories:
+
+- Health  
+- Emergency  
+- Anxiety  
+- Behavior  
+- Training  
+- Nutrition  
+- Grooming  
+
+This variety is important because the app needs to support different types of pet-owner questions.
+
+---
+
+## 8.4 Urgency Level Distribution
+
+![Distribution of Urgency Levels](hopepet_polished_readme_assets/09_4_distribution_of_urgency_levels.png)
+
+The dataset includes four urgency levels:
+
+- Low  
+- Medium  
+- High  
+- Emergency  
+
+This allows HOPEPET to provide different levels of guidance depending on the seriousness of the case.
+
+---
+
+## 8.5 Medical Background Distribution
+
+![Top Medical Background Categories](hopepet_polished_readme_assets/10_5_top_10_medical_background_categories.png)
+
+Medical background is important because the same symptom can require different guidance depending on the pet’s health history.
+
+---
+
+# 9. Relationship and Consistency Analysis
+
+## 9.1 Problem Category vs Urgency Level
+
+![Problem Category vs Urgency Level](hopepet_polished_readme_assets/11_1_problem_category_vs_urgency_level.png)
+
+This heatmap checks whether different problem categories are connected to reasonable urgency levels.
+
+Emergency cases should be strongly connected to Emergency urgency.  
+Training, grooming, and nutrition cases are usually less urgent.
+
+This supports the logic and responsibility of the dataset.
+
+---
+
+## 9.2 Pet Age Group and Urgency Level
+
+![Pet Age Group and Urgency Level](hopepet_polished_readme_assets/12_2_pet_age_group_and_urgency_level_bubble_chart.png)
+
+This bubble chart shows how pet age groups are distributed across urgency levels.
+
+It confirms that puppies, kittens, adult pets, and senior pets are represented across the dataset.
+
+---
+
+## 9.3 Emergency Signs and Urgency Distribution
+
+![Emergency Signs and Urgency Distribution](hopepet_polished_readme_assets/13_3_emergency_signs_and_urgency_distribution.png)
+
+This graph is one of the most important safety checks.
+
+Cases with emergency signs are connected to Emergency urgency.  
+This supports the safety logic of the dataset and helps ensure that high-risk cases receive appropriate recommendations.
+
+---
+
+## 9.4 Recommended Next Step by Urgency Level
+
+![Recommended Next Step by Urgency Level](hopepet_polished_readme_assets/14_4_recommended_next_step_by_urgency_level.png)
+
+This heatmap checks whether the recommended next step matches the urgency level.
+
+For example:
+
+- Low urgency cases should lead to home monitoring.  
+- Medium urgency cases should lead to close monitoring.  
+- High urgency cases should lead to contacting a veterinarian soon.  
+- Emergency cases should lead to immediate emergency veterinary care.  
+
+This confirms that the recommendations are consistent with the urgency level.
+
+---
+
+## 9.5 High-Risk Cases by Medical Background
+
+![High-Risk Cases by Medical Background](hopepet_polished_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.
+
+This is important because pets with existing medical conditions may require more careful guidance.
+
+---
+
+## 9.6 Recommended Next Step by Problem Category
+
+![Recommended Next Step by Problem Category](hopepet_polished_readme_assets/16_6_recommended_next_step_by_problem_category.png)
+
+This graph shows how recommended next steps vary across problem categories.
+
+It demonstrates that the dataset does not provide the same recommendation for every case, but adjusts the next step based on the type and seriousness of the problem.
+
+---
+
+## 9.7 High-Risk Rate by Appetite and Energy
+
+![High-Risk Rate by Appetite and Energy](hopepet_polished_readme_assets/17_6_high_risk_rate_by_appetite_status_and_energy_level.png)
+
+This graph checks the relationship between appetite status, energy level, and high-risk cases.
+
+This is useful because appetite and energy are important indicators in pet-care situations.
+
+---
+
+## 9.8 Risk Lift by Recent Change
+
+![Risk Lift by Recent Change](hopepet_polished_readme_assets/18_7_risk_lift_by_recent_change.png)
+
+This graph shows whether recent changes are associated with higher or lower high-risk rates compared to the overall dataset.
+
+Recent changes can be important context when evaluating a pet’s condition.
+
+---
+
+# 10. Text Analysis for Embeddings
+
+The recommendation system uses the `retrieval_text` column.
+
+The `retrieval_text` field combines important structured case information into one searchable text.
+
+It includes:
+
+- Pet type  
+- Age group  
+- Medical background  
+- Main symptom  
+- Secondary symptoms  
+- Symptom duration  
+- Appetite status  
+- Energy level  
+- Pain signs  
+- Emergency signs  
+- Urgency level  
+- Recommended next step  
+
+This gives the embedding model more context than using the user question alone.
+
+The reason I used `retrieval_text` is that semantic search works better when the model receives the full context of the case, not only the short user question.
+
+---
+
+# 11. Recommendation with Embeddings
+
+The recommendation task is a text-to-vector similarity task.
+
+Each case in the dataset is converted into a numerical vector using a Hugging Face embedding model.
+
+The user input is also converted into a vector.
+
+Then, cosine similarity is used to retrieve the most similar cases from the dataset.
+
+The recommendation pipeline is:
+
+1. User enters a pet-care question.  
+2. The question is converted into an embedding.  
+3. The system compares it to all saved dataset embeddings.  
+4. The system retrieves the top 3 most similar cases.  
+5. The retrieved cases are used as context for the generation step.  
+
+---
+
+## 11.1 Tested Hugging Face Embedding Models
+
+I tested three Hugging Face embedding models:
+
+| Model | Type |
+|---|---|
+| `sentence-transformers/all-MiniLM-L6-v2` | Text embedding |
+| `sentence-transformers/paraphrase-MiniLM-L3-v2` | Text embedding |
+| `sentence-transformers/all-mpnet-base-v2` | Text embedding |
+
+The models were evaluated using test queries with expected problem categories.
+
+The score used here is a retrieval hit rate, not traditional classification accuracy.  
+A Top 3 hit means that the expected problem category appeared somewhere within the top 3 retrieved cases.
+
+---
+
+## 11.2 Embedding Model Evaluation
+
+| Model | Embedding Dimension | Runtime Seconds | Top 3 Category Hit Rate | Top 5 Category 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 |
+
+![Embedding Evaluation](hopepet_polished_readme_assets/00_embedding_evaluation_polished.png)
+
+---
+
+## 11.3 Selected Embedding 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  
+- 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 has the shape:
+
+`(10000, 384)`
+
+This means that each of the 10,000 pet-care cases was converted into a 384-dimensional vector.
+
+The embeddings were saved so the app can load them directly without recalculating them every time.
+
+---
+
+# 12. Recommendation Output
+
+The recommendation function returns the top 3 most similar cases.
+
+Each recommendation includes:
+
+- Case ID  
+- Pet type  
+- Pet age group  
+- Problem category  
+- Urgency level  
+- Recommended next step  
+- Short recommendation  
+- Veterinary warning  
+- Similarity score  
+
+Example input:
+
+> My senior cat stopped eating today and seems very tired.
+
+Expected behavior:
+
+The system should retrieve cases related to cats, appetite loss, tiredness, health or nutrition concerns, and higher urgency.
+
+Another example input:
+
+> My dog is shaking and hiding during fireworks.
+
+Expected behavior:
+
+The system should retrieve dog-related anxiety cases.
+
+---
+
+# 13. Generation Component
+
+HOPEPET includes a Generative AI component using a Hugging Face model.
+
+The generation component receives:
+
+- The user question  
+- The top 3 retrieved similar cases  
+- Problem category  
+- Urgency level  
+- Triage reason  
+- Safe first steps  
+- Recommended next step  
+- 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  
+- Not a medical diagnosis  
+
+---
+
+# 14. Generated Response Structure
+
+The generated response should include:
+
+1. Main concern  
+2. Estimated urgency level  
+3. Recommended next step  
+4. Safe first steps  
+5. Veterinary warning  
+6. Safety disclaimer  
+
+Example response structure:
+
+> Based on similar cases, this situation may be related to a health concern.  
+> The estimated urgency level is High.  
+> Contact a veterinarian as soon as possible, especially if the pet is not eating, seems weak, shows pain, or the condition is worsening.  
+> This app provides general guidance only and does not replace professional veterinary advice.
+
+---
+
+# 15. Final Application Logic
+
+The final application combines recommendation and generation.
+
+The app flow is:
+
+1. The user describes a pet-care problem.  
+2. The app converts the input into an embedding.  
+3. The app retrieves the top 3 most similar cases.  
+4. The app uses the retrieved cases as context.  
+5. A Hugging Face generative model creates one final response.  
+6. The user receives both similar case information and a generated explanation.  
+
+The final app displays:
+
+- User input  
+- Top 3 similar cases  
+- AI-generated response  
+- Safety disclaimer  
+
+---
+
+# 16. Quick Starter Examples
+
+The final Gradio app includes three quick starter examples:
+
+1. `My dog is shaking and hiding during fireworks.`  
+2. `My senior cat stopped eating today and seems very tired.`  
+3. `My puppy keeps biting my hands during playtime.`  
+
+These examples test different parts of the system:
+
+- Anxiety  
+- Health / nutrition concern  
+- Training  
+
+---
+
+# 17. Technologies Used
+
+The project uses:
+
+- Python  
+- Pandas  
+- NumPy  
+- Matplotlib  
+- Scikit-learn  
+- Sentence Transformers  
+- Hugging Face Transformers  
+- Hugging Face Models  
+- Gradio  
+- Google Colab  
+
+---
+
+# 18. Safety Disclaimer
+
+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.
+
+The app should not be used for diagnosis or emergency decision-making.
+
+---
+
+# 19. Project Limitations
+
+This project has several limitations:
+
+- The dataset is synthetic.  
+- The app does not diagnose medical conditions.  
+- The app does not replace a veterinarian.  
+- The generated response depends on the quality of the retrieved similar cases.  
+- The model should be used only for general first-step guidance.  
+- Real-world deployment would require expert veterinary review and stronger safety validation.  
+
+---
+
+# 20. Future Improvements
+
+Possible future improvements include:
+
+- Adding real anonymized veterinary guidance data  
+- Adding more pet types  
+- Improving the generation model  
+- Adding multilingual support  
+- Adding stronger safety filters  
+- Adding user feedback  
+- Improving recommendation evaluation with more test queries  
+- Adding more detailed emergency detection  
+- Adding structured user forms for more accurate recommendations  
+
+---
+
+# 21. Final Summary
+
+HOPEPET demonstrates a complete AI application pipeline.
+
+The project includes:
+
+1. Synthetic dataset creation  
+2. Data validation  
+3. Descriptive statistics  
+4. Exploratory Data Analysis  
+5. Embedding-based recommendation  
+6. Hugging Face text generation  
+7. User-facing AI response  
+
+The project shows how retrieval and generation can work together to create a responsible AI assistant for pet-care guidance.
+
+The recommendation system retrieves similar cases, and the generation component turns those cases into a clear and safety-focused response for the user.