Spaces:

gladguy
/

SimpleProject

Sleeping

App Files Files Community

gladguy commited on Nov 30, 2025

Commit

b6ada5c

1 Parent(s): fc72d49

Final submission

Browse files

Files changed (1) hide show

README.md +89 -104

README.md CHANGED Viewed

@@ -8,125 +8,110 @@ sdk: gradio
 sdk_version: 6.0.0
 app_file: app.py
 pinned: false
 ---
-# 🩺 AnatomyBot - MBBS Anatomy Tutor
-An interactive Gradio application designed to help MBBS students learn human anatomy through visual diagrams, AI-generated educational content, and active recall simulations.
-## 📝 What I want to showcase
-I want to showcase an intelligent, interactive educational platform designed specifically for MBBS (medical) students. The goal is to bridge the gap between static textbooks and active learning by providing:
--   **Visual & Contextual Learning**: Instantly fetching relevant anatomical diagrams alongside AI-generated educational summaries.
--   **Active Recall & Simulation**: A "VIVA Mode" that simulates an oral anatomy exam with a strict but fair AI professor, complete with voice interaction.
--   **Resource Augmentation**: A "Book Mode" that allows students to upload their own textbooks and get AI-powered analysis and quiz questions for specific pages.
-## �️ What I've built so far
-I have built a fully functional **Gradio** web application that integrates multiple powerful AI services:
-### 1. Smart Query Engine
-*   **Anatomy Validation**: Uses **Hyperbolic AI (Llama 3.3 70B)** to ensure questions are strictly anatomy-related.
-*   **Visuals**: Fetches high-quality diagrams using **SERPAPI (Google Images)**, filtering out non-diagrammatic results.
-*   **Educational Content**: Generates structured, emoji-rich summaries (Location, Features, Clinical Significance).
-### 2. VIVA Training Mode
-*   **Exam Simulation**: Simulates a real oral exam environment with progressive difficulty.
-*   **Voice Interaction**: Uses **ElevenLabs** to vocalize questions for an immersive experience.
-*   **AI Evaluation**: Grades student answers (Distinction, Pass, Borderline, Fail) and provides detailed feedback with reference answers.
-### 3. Book Learning Mode
-*   **PDF Analysis**: Allows students to upload their own textbooks.
-*   **Page Extraction**: Extracts and displays specific pages for focused study.
-*   **AI Tutor**: Analyzes page content to generate summaries, clinical points, and self-test questions.
-### 4. Student System
-*   **Registration**: Includes a registration system (SQLite backend) to track student details (Name, Medical School, Year).
-## 💻 Tech Stack
-*   **Frontend/UI**: Gradio (Python)
-*   **LLM Intelligence**: Hyperbolic AI API (Meta Llama 3.3 70B Instruct)
-*   **Image Search**: SERPAPI (Google Images Engine)
-*   **Voice Synthesis**: ElevenLabs API (Text-to-Speech)
-*   **Database**: SQLite (for user management)
-*   **Image/PDF Processing**: Pillow, PyPDF2, pdf2image
-*   **Environment**: Python, Hugging Face Spaces
-## 🚀 Setup & Installation
 ### Prerequisites
 - Python 3.8 or higher
-- SERPAPI API Key ([Get one here](https://serpapi.com/))
-- Hyperbolic API Key ([Get one here](https://hyperbolic.xyz/))
-- ElevenLabs API Key ([Get one here](https://elevenlabs.io/))
-### Installation Steps
-1. Clone or download this project:
-```bash
-cd SimpleHF
-```
-2. Install dependencies:
-```bash
-pip install -r requirements.txt
-```
-3. Configure your API keys in `.env`:
-```bash
-SERPAPI_KEY=your_actual_serpapi_key
-HYPERBOLIC_API_KEY=your_actual_hyperbolic_key
-ELEVENLABS_API_KEY=your_actual_elevenlabs_key
-```
-## 🎮 Usage
-### Local Development
-Run the application:
-```bash
-python app.py
-```
-The app will launch at `http://localhost:7860`
-### Example Questions
-- "Show me the Circle of Willis"
-- "Brachial plexus anatomy"
-- "Carpal bones arrangement"
-- "Layers of the scalp"
-- "Anatomy of the heart chambers"
-## ☁️ Deployment to Hugging Face Spaces
-1. Create a new Space on [Hugging Face](https://huggingface.co/spaces)
-2. Select **Gradio** as the SDK
-3. Upload all files: `app.py`, `requirements.txt`, `README.md`
-4. Add your API keys as **Secrets** in Space settings:
-   - `SERPAPI_KEY`
-   - `HYPERBOLIC_API_KEY`
-   - `ELEVENLABS_API_KEY`
-5. Your app will automatically deploy!
-## 📂 Project Structure
-```
-SimpleHF/
-├── app.py              # Main application logic
-├── capp.py             # Extended application logic (if applicable)
-├── requirements.txt    # Python dependencies
-├── .env               # API keys (not committed to git)
-└── README.md          # This documentation
-```
-## ⚠️ Security Note
-Never commit your `.env` file with actual API keys to version control. The included `.env` is a template only.
-## 📄 License
-This project is for educational purposes.
-## 🤝 Support
-For issues or questions, please refer to the documentation or create an issue in the repository.

 sdk_version: 6.0.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: AnatomyBot - Interactive AI-powered MBBS anatomy tutor.
+tags:
+  - building-mcp-track-enterprise
+  - building-mcp-track-customer
+  - building-mcp-track-creative
 ---
+# 🩺 AnatomyBot – MBBS Anatomy Tutor
+Welcome to our submission for the **Hugging Face MCP 1st Birthday Hackathon**!
+This project showcases **an intelligent multi-agent educational system** powered by **Gradio**, designed to revolutionize how medical students learn anatomy through **visuals, voice interaction, and active recall**.
+**Link to demo:** [https://huggingface.co/spaces/gladguy/SimpleProject](https://huggingface.co/spaces/gladguy/SimpleProject)
+**YouTube Video:** [https://www.youtube.com/watch?v=5L5suQMTd5I](https://www.youtube.com/watch?v=5L5suQMTd5I)
+---
+## 🌐 Project Overview
+This system leverages specialized AI agents that collaborate to create an immersive learning experience:
+- 🛡️ **Validator Agent**: Ensures all queries are strictly anatomy-related using **Hyperbolic AI**.
+- 🖼️ **Visual Agent**: Instantly fetches and filters high-quality anatomical diagrams via **SERPAPI**.
+- 👨‍⚕️ **Professor Agent**: Conducts oral VIVA exams, generating questions and vocalizing them using **ElevenLabs**.
+- 🧠 **Analyst Agent**: Reads and interprets uploaded textbook pages to generate summaries and quizzes.
+---
+## 🗂️ Data Sources & External APIs
+Our platform relies on **state-of-the-art AI models and real-time data**. Each component is powered by a dedicated API to ensure accuracy and engagement.
+**Here is a detailed overview of the APIs and data sources leveraged by the agents:**
+1.  **Hyperbolic AI (Llama 3.3 70B)** – *The Brain*
+    *   Used for query validation, educational content generation, and student answer evaluation.
+2.  **SERPAPI (Google Images)** – *The Eyes*
+    *   Provides real-time access to high-quality medical diagrams and illustrations.
+3.  **ElevenLabs** – *The Voice*
+    *   Powers the "Professor Agent" to speak VIVA questions, simulating a real oral exam.
+---
+## 🧩 Core Components
+### 🎨 User Interface (`app.py`)
+-   **Interactive Gradio Interface**: A clean, tabbed UI optimized for learning.
+-   **Real-time Feedback**: Instant visual and audio responses.
+-   **Navigation**: Seamless switching between Learning, VIVA, and Book modes.
+### 🧠 Logic & Agents (`capp.py`)
+-   **Agent Definitions**: Contains the logic for the Validator, Visual, and Professor agents.
+-   **State Management**: Handles user sessions, VIVA progress, and PDF processing.
+### 💾 Data Persistence (`students.db`)
+-   **Student Records**: SQLite database to track registered students (Name, Medical School, Year).
+---
+## 🔗 Quick Links
+- 🏆 **Hackathon:** [MCP 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday)
+- 📺 **YouTube Demo:** [Watch Video](https://www.youtube.com/watch?v=5L5suQMTd5I)
+- 🚀 **Live Demo:** [Try AnatomyBot](https://huggingface.co/spaces/gladguy/SimpleProject)
+- 💼 **LinkedIn Post:** [View Post](https://www.linkedin.com/posts/gladguy_learn-anatomy-with-ai-activity-7400990572884168705-14Ln/)
+---
+## 🛠️ Installation & Setup
 ### Prerequisites
 - Python 3.8 or higher
+- API Keys for SERPAPI, Hyperbolic, and ElevenLabs.
+### Steps
+1.  Clone the repository:
+    ```bash
+    git clone https://huggingface.co/spaces/gladguy/SimpleProject
+    cd SimpleProject
+    ```
+2.  Install dependencies:
+    ```bash
+    pip install -r requirements.txt
+    ```
+3.  Set up your `.env` file:
+    ```bash
+    SERPAPI_KEY=your_key
+    HYPERBOLIC_API_KEY=your_key
+    ELEVENLABS_API_KEY=your_key
+    ```
+4.  Run the app:
+    ```bash
+    python app.py or uv run app.py
+    ```
+---
+## 🧑‍💻 Authors
+-   **Waheed** – *Lead Developer & AI Architect*
+---
+## 📝 License
+This project is licensed under the MIT License.