Initial commit: Hugging Face Spaces app setup

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,52 @@
+pyproject.toml
+poetry.lock
+.venv
+.env
+.DS_Store
+__pycache__
+.pytest_cache
+.ruff_cache
+.vscode
+.idea
+.cursorrules
+uv.lock
+
+
+# Python
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+
+# IDE
+*.swp
+*.swo
+.project
+.pydevproject
+.settings/
+
+# Logs
+*.log
+
+# OS
+Thumbs.db

README.md

@@ -0,0 +1,102 @@
+---
+title: Agentic Coach Advisor Medgemma
+emoji: 💬
+colorFrom: yellow
+colorTo: purple
+sdk: gradio
+sdk_version: 5.0.1
+app_file: app.py
+pinned: false
+license: mit
+short_description: Using medGemma as an agent for giving basic health coaching
+---
+
+
+
+# MedGemma Agent: AI-Powered Medical Assistant
+
+![MedGemma Agent](assets/logo.png)
+
+## 🏥 Overview
+
+MedGemma Agent is an advanced AI-powered medical assistant that provides accessible and accurate medical information to patients and non-medical professionals. Built on top of Google's MedGemma model, this application combines state-of-the-art medical language understanding with multimodal capabilities to deliver clear, concise, and reliable medical insights.
+
+## ✨ Key Features
+
+- **Multimodal Understanding**: Process both text queries and medical images
+- **Real-time Responses**: Stream responses for an interactive experience
+- **Wikipedia Integration**: Access to verified medical information
+- **User-friendly Interface**: Clean, modern UI with example queries
+- **Secure API**: Protected endpoints with API key authentication
+
+## 🚀 Technical Implementation
+
+### Backend Architecture
+
+The application is built using:
+- **Modal**: For serverless deployment and GPU acceleration
+- **FastAPI**: For robust API endpoints
+- **VLLM**: For efficient model inference
+- **MedGemma-4B**: Fine-tuned medical language model
+- **Wikipedia API**: For additional medical context
+
+### Key Components
+
+1. **Model Deployment**
+   - Utilizes Modal's GPU-accelerated containers
+   - Implements efficient model loading with VLLM
+   - Supports bfloat16 precision for optimal performance
+
+2. **API Layer**
+   - Streaming responses for real-time interaction
+   - Secure API key authentication
+   - Base64 image processing for multimodal inputs
+
+3. **Frontend Interface**
+   - Built with Gradio for seamless user interaction
+   - Custom CSS theming for professional appearance
+   - Example queries for common medical scenarios
+
+## 🛠️ Usage
+
+1. **Text Queries**
+   - Ask medical questions in natural language
+   - Get clear, patient-friendly explanations
+   - Example: "What are the symptoms of a stroke?"
+
+2. **Image Analysis**
+   - Upload medical images for analysis
+   - Get AI-powered insights about the image
+   - Supports common medical image formats
+
+## 🔒 Security
+
+- API key authentication for all requests
+- Secure image processing
+- Protected model endpoints
+
+## 🏗️ Technical Stack
+
+- **Backend**: Modal, FastAPI, VLLM
+- **Frontend**: Gradio
+- **Model**: MedGemma-4B (unsloth/medgemma-4b-it-unsloth-bnb-4bit)
+- **Additional Tools**: Wikipedia API for medical context
+
+## 🎯 Performance
+
+- Optimized for low latency responses
+- GPU-accelerated inference
+- Efficient memory utilization with 4-bit quantization
+- Maximum context length of 8192 tokens
+
+## 🤝 Contributing
+
+We welcome contributions! Please feel free to submit issues and pull requests.
+
+## 📝 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+---
+
+Built with ❤️ for the Hugging Face Spaces Hackathon.

app.py

@@ -0,0 +1,154 @@
+import gradio as gr
+import httpx
+import os
+import json
+import base64
+from PIL import Image
+import io
+import docs  
+
+API_KEY = os.getenv("API_KEY")  
+MODAL_API_ENDPOINT = os.getenv("MODAL_API_ENDPOINT")
+
+def encode_image_to_base64(image):
+    if image is None:
+        return None
+    buffered = io.BytesIO()
+    image.save(buffered, format="PNG")
+    return base64.b64encode(buffered.getvalue()).decode()
+
+async def call_my_api(message, history, image=None):
+    # Support multimodal: message can be dict with 'text' and 'files'
+    user_text = message["text"] if isinstance(message, dict) else message
+    if user_text.strip().lower().startswith("(example)"):
+        user_text = user_text.strip()[9:].lstrip()
+    image_obj = None
+    
+    if image is None and isinstance(message, dict) and message.get("files"):
+        # message["files"] is a list of file paths or file objects
+        # For Gradio, it may be a list of PIL Images
+        image_obj = message["files"][0] if message["files"] else None
+    else:
+        image_obj = image
+    image_base64 = encode_image_to_base64(image_obj) if image_obj else None
+
+    payload = {
+        "prompt": "You are a helpful and positive health coach. Explain in simple terms to a patient or non-medical person on the following question or statement.\n\n" + user_text,
+        "image": image_base64
+    }
+
+    headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": API_KEY
+    }
+
+    try:
+        async with httpx.AsyncClient() as client:
+            async with client.stream('POST', MODAL_API_ENDPOINT, json=payload, headers=headers, timeout=120.0) as response:
+                response.raise_for_status()
+                async for line in response.aiter_lines():
+                    if line.startswith('data: '):
+                        try:
+                            data = json.loads(line[6:])  # Remove 'data: ' prefix
+                            if data['type'] == 'final':
+                                yield data['content']['response']
+                            elif data['type'] == 'thinking':
+                                yield data['content'].get('message', '')
+                            elif data['type'] == 'tool_call':
+                                yield f"Using tool: {data['content'].get('name', '')}"
+                            elif data['type'] == 'tool_result':
+                                yield f"Tool result: {data['content'].get('result', '')}"
+                        except json.JSONDecodeError:
+                            continue
+    except httpx.RequestError as e:
+        print(f"Error calling API: {e}")
+        yield f"Error: Could not connect to the API. {e}"
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+        yield "An unexpected error occurred."
+
+
+def vote(chatbot, history, vote):
+    print(f"Vote: {vote}")
+    print(f"Chatbot: {chatbot}")
+    print(f"History: {history}")
+    return chatbot, history
+
+with gr.Blocks(
+    theme=gr.themes.Soft(
+        primary_hue="blue",
+        secondary_hue="blue",
+        neutral_hue="slate",
+        font=["Inter", "sans-serif"],
+    ),
+    css_paths=["assets/custom.css"],
+    title="Agent medGemma"
+) as demo:
+    chatbot = gr.Chatbot(
+        placeholder="Ask me anything about a medical condition. \n\nYou can also upload an medical image to get more information.",
+        type="messages",
+        height=600
+    )
+    chatbot.like(vote, inputs=[chatbot, gr.State([]), gr.State("")], outputs=[chatbot, gr.State([])])
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            gr.Markdown("# 🏥 Agent MedGemma", elem_id="main-title")
+        with gr.Column(scale=3):
+            gr.Markdown(
+                "<div class='tagline'>Simple and accessible medical facts</div>",
+                elem_id="main-tagline"
+            )
+
+    with gr.Row():
+        with gr.Column(scale=1, elem_id="chat-col"):
+            chat_interface = gr.ChatInterface(
+                multimodal=True,
+                fn=call_my_api,
+                chatbot=chatbot,
+                theme="soft",
+                examples=[
+                    "(example) Tell me about the causes of a heart attack.",
+                    "(example) What should I do with serious vomiting?",
+                    "(example) Should I take double my insulin now that I forgot to take it?",
+                    "(example) What are the most common symptoms of a stroke?"
+                ],
+                example_icons=["assets/heartbreak.svg",
+                                "assets/sickface.svg",
+                                "assets/injection.svg",
+                                "assets/brain.svg"]
+            )
+
+    gr.Markdown(
+        "Ask me anything about a medical condition.<br><br>You can also upload an medical image to get more information.",
+        elem_id="main-instructions"
+    )
+
+    gr.Markdown(
+        """
+        <div class='disclaimer-box'>
+            <p>
+                <strong>Medical Disclaimer:</strong> This AI assistant is designed for educational and informational purposes only. 
+                It does not constitute medical advice, diagnosis, or treatment. Always consult with qualified healthcare professionals 
+                for medical decisions. This tool aims to promote health literacy and empower individuals to better understand their 
+                health, but should not replace professional medical consultation.
+            </p>
+        </div>
+        """,
+        elem_id="disclaimer"
+    )
+
+    gr.Markdown(
+        """
+        <div style='text-align: center; margin-top: 20px; padding: 10px; border-top: 1px solid #e0e0e0;'>
+            <a href='/docs' style='text-decoration: none; color: #666;'>📚 View Technical Documentation</a>
+        </div>
+        """,
+        elem_id="footer"
+    )
+
+with demo.route("Technical Documentation", "/docs"):
+    docs.docs_demo.render()
+
+if __name__ == "__main__":
+    demo.launch(favicon_path="assets/medical_cross_icon_144218.ico")

assets/custom.css

@@ -0,0 +1,131 @@
+/* Custom Gradio Styles */
+.gradio-container {
+    margin: auto;
+    padding: 20px;
+}
+.gradio-markdown {
+    padding: 20px;
+}
+#main-title {
+    display: flex;
+    align-items: center;
+    height: 100%;
+}
+#main-tagline {
+    display: flex;
+    align-items: center;
+    height: 100%;
+    justify-content: flex-end;
+}
+.tagline {
+    color: #4b5563;
+    font-size: 1.2em;
+    margin-bottom: 0;
+    text-align: right;
+}
+.gradio-markdown h1 {
+    color: #2563eb;
+    font-size: 2.5em;
+    margin-bottom: 10px;
+    text-align: left;
+}
+.gradio-chatbot, .gradio-image, .gradio-interface, .gradio-column {
+    border: 1.5px solid #cbd5e1;
+    border-radius: 10px;
+    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.07);
+    background: #f8fafc;
+    padding: 12px;
+    min-height: 600px;
+    height: 600px;
+    box-sizing: border-box;
+}
+.gradio-button {
+    border-radius: 8px;
+    transition: all 0.3s ease;
+}
+.gradio-button:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+}
+
+/* DARK MODE OVERRIDES */
+@media (prefers-color-scheme: dark) {
+    body, .gradio-container {
+        background: #181a20 !important;
+    }
+    #main-title h1 {
+        color: #60a5fa;
+    }
+    .tagline {
+        color: #cbd5e1;
+    }
+    .gradio-chatbot, .gradio-image, .gradio-interface, .gradio-column {
+        background: #23262f;
+        border: 1.5px solid #334155;
+        min-height: 600px;
+        height: 600px;
+        box-sizing: border-box;
+    }
+}
+
+#chat-col, #img-col {
+    border: 2px solid #cbd5e1 !important;
+    border-radius: 10px !important;
+    background: #f8fafc !important;
+    box-sizing: border-box;
+    padding: 12px;
+}
+@media (prefers-color-scheme: dark) {
+    #chat-col, #img-col {
+        border: 2px solid #60a5fa !important;
+        background: #23262f !important;
+    }
+}
+
+.disclaimer-box {
+    background: rgba(30, 41, 59, 0.7); /* semi-transparent dark slate */
+    border-left: 4px solid #2563eb;    /* blue-600 */
+    padding: 15px;
+    margin: 20px 0;
+    border-radius: 4px;
+    color: var(--body-text-color, #f1f5f9); /* fallback to light text */
+    font-size: 0.95em;
+}
+body.light .disclaimer-box {
+    background: rgba(248, 249, 250, 0.85); /* light background for light mode */
+    color: #495057;
+}
+
+#footer a {
+    color: #a1a1aa !important;
+    font-size: 1em;
+    text-decoration: none;
+    transition: color 0.2s;
+}
+#footer a:hover {
+    color: #2563eb !important;
+    text-decoration: underline;
+}
+
+#main-instructions {
+    text-align: center;
+    margin-top: 2em;
+    margin-bottom: 2em;
+    font-size: 1.12em;
+    color: #a1a1aa; /* subtle gray for less prominence */
+    font-weight: 400;
+    letter-spacing: 0.01em;
+}
+
+#docs-demo {
+    max-width: 800px;
+    margin: 2em auto;
+    background: rgba(30,41,59,0.7);
+    border-radius: 8px;
+    padding: 2em;
+    color: var(--body-text-color, #f1f5f9);
+}
+body.light #docs-demo {
+    background: rgba(248,249,250,0.95);
+    color: #23262f;
+} 

docs.py

@@ -0,0 +1,127 @@
+import gradio as gr
+import os
+
+
+with gr.Blocks(title="Technical Documentation", css="footer {visibility: hidden}") as docs_demo:
+    
+    with gr.Column():
+        gr.Markdown("""
+        # Technical Documentation
+
+        ## Overview
+        This page provides details about the architecture, API, and usage of the MedGemma Agent application.
+
+        ## Features
+        - Multimodal (text + image)
+        - Wikipedia tool integration
+        - Real-time streaming
+        - Medical knowledge base
+
+        ---
+
+        ## Architecture
+        - **Frontend:** Gradio Blocks, custom CSS
+        - **Backend:** Modal, FastAPI, VLLM, MedGemma-4B
+        - **Security:** API key authentication
+
+        ### 🏗️ Technical Stack
+        - Streaming responses for real-time interaction
+        - Secure API key authentication
+        - Base64 image processing for multimodal inputs 
+
+        ### Frontend Interface
+        - Built with Gradio for seamless user interaction
+        - Custom CSS theming for professional appearance
+        - Example queries for common medical scenarios            
+
+        ```mermaid
+        graph TD
+            A[MedGemma Agent] --> B[Backend]
+            A --> C[Frontend]
+            A --> D[Model]
+            
+            B --> B1[Modal]
+            B --> B2[FastAPI]
+            B --> B3[VLLM]
+            
+            C --> C1[Gradio]
+            C --> C2[Custom CSS]
+            
+            D --> D1[MedGemma-4B]
+            D --> D2[4-bit Quantization]
+        ```
+        """)
+        
+        gr.Markdown("""
+        ## Backend Architecture
+        
+        ### 🎯 Performance Features
+        
+        - Optimized for low latency responses
+        - GPU-accelerated inference
+        - Efficient memory utilization with 4-bit quantization
+        - Maximum context length of 8192 tokens
+        
+        ### 🔒 Security Measures
+        
+        - API key authentication for all requests
+        - Secure image processing
+        - Protected model endpoints
+                    
+        ```mermaid
+        flowchart LR
+            A[Client] --> B[FastAPI]
+            B --> C[Modal Container]
+            C --> D[VLLM]
+            D --> E[MedGemma-4B]
+            B --> F[Wikipedia API]
+        ```
+        """)
+        with gr.Row():
+            with gr.Column():
+                gr.Markdown("""
+                ## 💾 Model Deployment
+                
+                ### Model
+                - **Model:** unsloth/medgemma-4b-it-unsloth-bnb-4bit
+                - **Context Length:** 8192 tokens
+                - **Quantization:** 4-bit, bfloat16
+                - Utilizes Modal's GPU-accelerated containers
+                - Implements efficient model loading with VLLM
+                - Supports bfloat16 precision for optimal performance
+                """)
+            with gr.Column():
+                gr.Markdown("""
+                ```mermaid
+                graph TD
+                    A[Model Loading] --> B[GPU Acceleration]
+                    B --> C[4-bit Quantization]
+                    C --> D[8192 Token Context]
+                    D --> E[Streaming Response]
+                ```
+                """)
+    with gr.Column():
+        gr.Markdown("""
+        ## 📊 System Architecture
+        
+        ```mermaid
+        flowchart TD
+            A[User Interface] --> B[API Gateway]
+            B --> C[Authentication]
+            C --> D[Model Service]
+            D --> E[Wikipedia Service]
+            D --> F[Image Processing]
+            F --> G[Model Inference]
+            E --> H[Response Generation]
+            G --> H
+            H --> I[Stream Response]
+            I --> A
+        ```
+        """)
+        
+        gr.Markdown("""
+        [Back to Main Application](https://huggingface.co/spaces/Agents-MCP-Hackathon/agentic-coach-advisor-medgemma)
+        """)
+
+if __name__ == "__main__":
+    docs_demo.launch()

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=4.0.0
+httpx>=0.24.0
+Pillow>=10.0.0
+python-multipart>=0.0.6