Initial commit.

README.md

@@ -1,14 +1,84 @@
 ---
-title: Fungi Sage Vision
-emoji: 👀
+title: FungiSage Vision (Gradio UI)
+emoji: 🍄🤖
 colorFrom: gray
 colorTo: pink
 sdk: gradio
 sdk_version: 5.36.2
-app_file: app.py
+app_file: src/app.py
 pinned: false
 license: apache-2.0
-short_description: 'Powered by musheff: AI that knows its fungi.'
+short_description: "Powered by musheff: AI that knows its fungi."
+tags:
+  - gradio
+  - vision
+  - mushroom
+  - musheff
+datasets:
+  - SoFa325/12_popular_russia_mushrooms_edible_poisonous
+models:
+  - blasisd/musheff
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FungiSage Vision: Where data meets delicious—or dangerous
+
+FungiSage Vision transforms foraging into a safe, science-backed adventure. Powered by our [`musheff`](https://huggingface.co/blasisd/musheff) model (a fine-tuned EfficientNet-B3 trained on _SoFa325/12_popular_russia_mushrooms_edible_poisonous_), it identifies 12 common Russian species in seconds—delivering instant edibility/toxicity alerts with the solid reliability of a mountain massif. Snap a photo, and forage with AI-powered confidence.
+
+## Getting Started
+
+This guide provides step-by-step instructions to set up and run the project on your local machine for development and testing purposes. For details on deploying the project to a production environment, refer to the Deployment section.
+
+### Prerequisites
+
+To set up and run this project, ensure the following software and tools are installed on your system:
+
+- **Python**: Version `3.10.12` or higher is required. Verify your Python version by running:
+
+  ```bash
+  python3 --version
+  ```
+
+- **Dependencies**: Install the required Python packages listed in requirements.txt using pip. Run the following command in your terminal:
+
+  ```bash
+  pip install -r requirements.txt
+  ```
+
+- **Backend server**: This project is the frontend component only. Before proceeding, ensure you've deployed the backend server:
+  1. **Deploy the backend:**
+     - Implementation → [blasisd/musheff-api](https://huggingface.co/spaces/blasisd/musheff-api/tree/main).
+  2. **Configure environment variable:**
+     - Set `MUSHEFF_API_ENDPOINT` in your environment to point to your live backend URL.
+
+### Local Development and Testing
+
+To run the application locally for development and testing purposes, execute the following command in your terminal:
+
+```bash
+python app.py
+```
+
+> [!WARNING]
+> Ensure you are in the project's **src** directory before running the script or adapt running path.
+
+## Deployment
+
+### Deployment on Hugging Face Spaces
+
+To deploy the project on Hugging Face Spaces, follow these steps:
+
+1. Create an account on [Hugging Face](https://huggingface.co) if you don’t already have one.
+
+2. Refer to the official [Spaces Overview](https://huggingface.co/docs/hub/en/spaces-overview) documentation for detailed instructions on setting up and deploying your project.
+
+### Deployment on Other Cloud Platforms
+
+For deployment on other cloud or live systems, consult the documentation provided by your chosen service provider. Each platform may have specific requirements and steps for deploying Python-based applications.
+
+## Built With
+
+- [Python 3.10.12](http://www.python.org/) - Developing with the best programming language
+
+## Authors
+
+**Vlasios Dimitriadis** - _Initial work:_ [FungiSage Vision](https://huggingface.co/spaces/blasisd/fungi-sage-vision)

requirements.txt

@@ -0,0 +1,2 @@
+gradio==5.35.0
+python-dotenv==1.1.1

src/app.py

@@ -0,0 +1,283 @@
+import os
+from typing import Any
+
+import gradio as gr
+import requests
+
+from dotenv import load_dotenv
+
+
+load_dotenv()
+
+
+API_ENDPOINT = os.getenv("MUSHEFF_API_ENDPOINT")
+
+
+def classify_image(img_path: str) -> tuple[dict[str, Any]]:
+    """Classifies a mushroom image, returning species, edibility, and confidence score.
+    In case of error returns the error.
+
+    :param img_path: the path to the mushroom image
+    :type img_path: str
+    :return: confidence score, species, edibility or error message (as output or error components)
+    :rtype: tuple[dict[str, Any]]
+    """
+    try:
+        with open(img_path, "rb") as fp:
+            files = {"image_file": (fp.name, fp)}
+
+            # Calling the service
+            response = requests.post(API_ENDPOINT, files=files)
+
+            # Handle HTTP errors
+            if response.status_code != 200:
+                error_msg = response.json().get(
+                    "detail", f"API Error {response.status_code}"
+                )
+                return show_error(f"Backend Error: {error_msg}")
+
+            # Process successful response
+            data = response.json()
+            return show_results(data)
+
+    except requests.exceptions.Timeout:
+        return show_error("Request timed out. Please try again.")
+
+    except requests.exceptions.ConnectionError:
+        return show_error("Cannot connect to the server. Please check your connection.")
+    except TypeError:
+        return show_error("Invalid input. Please select a valid file and try again.")
+    except Exception as e:
+        return show_error(f"System error: {e}")
+
+
+def show_results(data: dict) -> tuple[dict[str, Any]]:
+    """Show the results data retrieved from the service
+    in the respective output components
+
+    :param data: the data retrieved from the classify service
+    :type data: dict
+    :return: the output components
+    :rtype: tuple[dict[str, Any]]
+    """
+
+    # Create visual output components
+    confidence = data["confidence"]
+    class_name = data["mushroom_type"]
+    edibility = data["toxicity_profile"]
+
+    return (
+        # Confidence output
+        gr.update(
+            value=generate_confidence_html(confidence),
+        ),
+        # Species display
+        gr.update(
+            value=generate_class_html(class_name),
+        ),
+        # Edibility alert
+        gr.update(
+            value=generate_edibility_html(edibility, confidence, class_name),
+        ),
+        gr.update(value=""),  # Error output
+    )
+
+
+def show_error(message: str) -> tuple[dict[str, Any]]:
+    """Update the error output component with the error message
+    Nullify all the other output components
+
+    :param message: the error message
+    :type message: str
+    :return: the error message component, along with the other nullified output components
+    :rtype: tuple[dict[str, Any]]
+    """
+    return (
+        gr.update(value=""),  # Confidence output
+        gr.update(value=""),  # Class output
+        gr.update(value=""),  # Edibility output
+        gr.update(value=generate_error_html(message)),  # Error alert
+    )
+
+
+def generate_confidence_html(confidence):
+    return f"""<div class="confidence-display" style="font-size:1.1rem">
+        <div class="confidence-header">
+            <span class="confidence-icon">📊</span>
+            <span class="confidence-title">Classification Confidence</span>
+        </div>
+
+        <div class="confidence-visual">
+            <div class="confidence-bar-bg">
+                <div class="confidence-bar-fill" style="width: {confidence*100:.2f}%"></div>
+            </div>
+            <div class="confidence-value">{confidence*100:.2f}%</div>
+        </div>
+    </div>
+    """
+
+
+def generate_class_html(class_name):
+    return f"""
+    <div style='
+        font-size: 1.5rem;
+        text-align: center;
+        padding: 20px;
+        background: #E3F2FD;
+        border-radius: 8px;
+    '>
+        🍄 <br><strong>{class_name.replace("_", " ")}</strong>
+    </div>
+    """
+
+
+def generate_edibility_html(edibility, confidence, class_name):
+    if edibility == "edible":
+        return (
+            f"<div class='edible-alert'>"
+            f"✅ SAFE TO EAT (with verification)<hr style='margin:10px 0;'>"
+            f"<div style='font-size:1.1rem'>"
+            f"Always confirm with mycologist before consumption"
+            f"</div></div>"
+        )
+    else:
+        return (
+            f"<div class='poison-alert'>"
+            f"☠️ <strong>POISONOUS!</strong> DO NOT CONSUME<hr style='margin:10px 0;'>"
+            f"<div style='font-size:1.1rem;color:var(--poison-color)'>"
+            f"Misidentification risk: {100 - confidence*100:.2f}%<br>"
+            f"<em>Immediately contact poison control if ingested</em>"
+            f"</div></div>"
+        )
+
+
+def generate_error_html(message):
+    return f"""
+    <div class='error-banner'>
+        <span class='error-icon'>❌</span>
+        <strong>CLASSIFICATION FAILED</strong><br>
+        {message}<br>
+        <em>Please try again or contact support</em>
+    </div>
+    """
+
+
+def toggle_row_visibility(*comp_vals):
+    """Update row visibility based on non empty value(s) of component(s) on row"""
+    return gr.Row(visible=any(comp_vals))
+
+
+def handle_image_change(new_image):
+    """This function will be called when image changes (cleared or new one selected)"""
+    # New image selected or deleted (new_image or None), in any case reset output components
+    return (
+        new_image,
+        gr.Row(visible=False),
+        gr.Row(visible=False),
+        gr.update(visible=False),
+    )
+
+
+def hr_line_update():
+    return gr.update(visible=True)
+
+
+# Custom HTML components
+safety_html = """
+<div class="safety-banner">
+    <div class="warning-icon">⚠️</div>
+    <strong>CRITICAL SAFETY NOTICE:</strong> FungiSage Vision provides probabilistic guidance only - not guarantees.
+    Mushroom misidentification can be fatal. Always consult certified mycologists before consumption.
+</div>
+"""
+
+slogan_html = """
+<div class="slogan-container">
+    <div class="mushroom-icon">🍄</div>
+    <div class="slogan-text">
+        <span class="brand-tagline">Massif Mushroom Intelligence.</span>
+        <div class="brand-action">
+            <span class="brand-name">FungiSage Vision</span> Guides,
+            <span class="verify-emphasis">You Verify.</span>
+        </div>
+    </div>
+</div>
+"""
+
+# CSS file path
+css_path = os.path.join(os.path.dirname(__file__), "static/styles/custom.css")
+
+with gr.Blocks(
+    theme=gr.themes.Glass(),
+    css_paths=css_path,
+) as demo:
+    gr.HTML(safety_html)
+    gr.HTML(slogan_html)
+
+    # Input section
+    with gr.Group(elem_id="inputsContainer"):
+        gr.Markdown("### Upload Mushroom Image", elem_id="uploadHeader")
+        image_input = gr.Image(type="filepath", label="", height=300)
+        classify_btn = gr.Button(
+            "Classify Mushroom", elem_id="classifyBtn", variant="primary"
+        )
+
+    # Output section
+    with gr.Group(elem_id="outputsContainer"):
+        with gr.Row(visible=False, scale=1, equal_height=True) as results_group:
+            with gr.Column(scale=1, elem_id="confCol"):
+                confidence_output = gr.HTML(
+                    label="Confidence Level", elem_classes="output-card"
+                )
+
+            with gr.Column(scale=2, elem_id="speciesCol"):
+                class_output = gr.HTML(
+                    label="Identified Species", elem_classes="output-card"
+                )
+
+            with gr.Column(scale=1, elem_id="edibilityCol"):
+                edibility_output = gr.HTML(
+                    label="Safety Assessment", elem_classes="output-card"
+                )
+
+        with gr.Row(visible=False) as errors_group:
+            error_output = gr.HTML(elem_classes="error-card")
+
+        # Used only for auto scrolling when results or errors occur
+        bottom_line = gr.HTML("<hr>", visible=False, elem_id="bottomLine")
+
+    # Classification function called on button click
+    classify_btn.click(
+        fn=classify_image,
+        inputs=image_input,
+        outputs=[
+            confidence_output,
+            class_output,
+            edibility_output,
+            error_output,
+        ],
+    ).then(
+        fn=toggle_row_visibility,
+        inputs=[confidence_output, class_output, edibility_output],
+        outputs=results_group,  # If any of the result outputs (got results from service), then show results row
+    ).then(
+        fn=toggle_row_visibility,
+        inputs=[error_output],
+        outputs=errors_group,  # If error occurred, then show errors row
+    ).then(
+        fn=hr_line_update,
+        inputs=[],
+        outputs=[bottom_line],
+        scroll_to_output=True,  # Useful to scroll there after results or errors occur
+    )
+
+    # Handle image changes (upload or clear/hide rows with results and errors)
+    image_input.change(
+        fn=handle_image_change,
+        inputs=image_input,
+        outputs=[image_input, results_group, errors_group, bottom_line],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

src/static/styles/custom.css

@@ -0,0 +1,343 @@
+/* ===== DESIGN SYSTEM ===== */
+:root {
+  /* Colors */
+  --primary-green: #2e7d32;
+  --light-green: #e8f5e9;
+  --dark-green: #1b5e20;
+  --warning-red: #d32f2f;
+  --light-red: #ffebee;
+  --text-dark: #333;
+  --text-light: #f8f9fa;
+
+  /* Spacing */
+  --spacing-xs: 0.5rem;
+  --spacing-sm: 0.8rem;
+  --spacing-md: 1.2rem;
+  --spacing-lg: 1.8rem;
+  --spacing-xl: 2.4rem;
+
+  /* Typography */
+  --font-size-xs: 0.8rem;
+  --font-size-sm: 0.9rem;
+  --font-size-base: 1rem;
+  --font-size-md: 1.2rem;
+  --font-size-lg: 1.5rem;
+  --font-size-xl: 2rem;
+
+  /* Effects */
+  --shadow: 0 0.25rem 0.5rem rgba(0, 0, 0, 0.1);
+  --border-radius: 0.5rem;
+}
+
+/* ===== SAFETY BANNER ===== */
+.safety-banner {
+  background: var(--light-red);
+  border: 0.15rem solid var(--warning-red);
+  border-radius: var(--border-radius);
+  padding: var(--spacing-md);
+  margin: 0 auto var(--spacing-lg) auto;
+  max-width: 60vw;
+  text-align: center;
+  box-shadow: var(--shadow);
+  font-size: var(--font-size-xs);
+  line-height: 1.5;
+}
+
+.warning-icon {
+  display: inline-block;
+  margin-right: var(--spacing-xs);
+  font-size: var(--font-size-lg);
+}
+
+/* ===== SLOGAN CONTAINER ===== */
+.slogan-container {
+  background: var(--light-green);
+  border: 0.15rem solid var(--primary-green);
+  border-radius: var(--border-radius);
+  padding: var(--spacing-md);
+  margin: 0 auto var(--spacing-lg) auto;
+  max-width: 90vw;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--spacing-md);
+  box-shadow: var(--shadow);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen,
+    sans-serif;
+}
+
+.mushroom-icon {
+  font-size: var(--font-size-xl);
+  flex-shrink: 0;
+}
+
+.slogan-text {
+  text-align: center;
+  line-height: 1.4;
+}
+
+.brand-tagline {
+  font-size: var(--font-size-lg);
+  font-weight: 600;
+  color: var(--dark-green);
+  display: block;
+}
+
+.brand-action {
+  font-size: var(--font-size-md);
+  color: var(--text-dark);
+  margin-top: var(--spacing-xs);
+}
+
+.brand-name {
+  font-weight: 700;
+  color: var(--dark-green);
+  text-decoration: underline;
+  text-underline-offset: 0.2rem;
+}
+
+.verify-emphasis {
+  font-weight: 700;
+  color: var(--warning-red);
+}
+
+/* ===== DARK MODE ADJUSTMENTS ===== */
+.dark .safety-banner {
+  background: #4a1c1c;
+  border-color: #e53935;
+}
+
+.dark .slogan-container {
+  background: #1a2a1a;
+  border-color: var(--primary-green);
+}
+
+.dark .brand-tagline,
+.dark .brand-name {
+  color: #a5d6a7;
+}
+
+.dark .brand-action {
+  color: #e0e0e0;
+}
+
+.dark .verify-emphasis {
+  color: #ff8a80;
+}
+
+/* ===== RESPONSIVE ADJUSTMENTS ===== */
+@media (max-width: 48rem) {
+  /* ≈768px */
+  .safety-banner,
+  .slogan-container {
+    max-width: 95vw;
+    padding: var(--spacing-sm);
+  }
+
+  .slogan-container {
+    flex-direction: column;
+    gap: var(--spacing-sm);
+  }
+
+  .brand-tagline {
+    font-size: var(--font-size-md);
+  }
+
+  .brand-action {
+    font-size: var(--font-size-base);
+  }
+}
+
+/* Main containers */
+#inputsContainer,
+#outputsContainer {
+  background: white;
+  border-radius: var(--border-radius);
+  box-shadow: var(--shadow);
+  padding: var(--spacing-md);
+  margin-bottom: var(--spacing-lg);
+  max-width: 90vw;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+/* Input section */
+#inputsContainer {
+  text-align: center;
+  border-top: 0.4rem solid var(--primary-green);
+}
+
+/* Source selection icons */
+#inputsContainer .image-container .source-selection .icon {
+  width: 2.5rem;
+  height: 2.5rem;
+}
+
+/* Button styling */
+#classifyBtn {
+  background: var(--primary-green) !important;
+  color: white !important;
+  font-weight: 600;
+  font-size: 1.1rem;
+  padding: 0.8em 1.6em;
+  border-radius: 0.3em;
+  margin-top: var(--spacing-sm);
+  transition: all 0.3s ease;
+}
+
+#classifyBtn:hover {
+  background: var(--dark-green) !important;
+  transform: translateY(-2px);
+  box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15);
+}
+
+/* Output columns */
+#confCol,
+#speciesCol,
+#edibilityCol {
+  padding: var(--spacing-md);
+  border-radius: var(--border-radius);
+  background: var(--light-green);
+  align-content: center;
+}
+
+#speciesCol {
+  background: #f1f8e9; /* Slightly different shade */
+}
+
+/* Column headers */
+.gr-output-label {
+  display: block;
+  font-weight: 700 !important;
+  font-size: 1.1rem !important;
+  color: var(--primary-green) !important;
+  margin-bottom: 0.6rem !important;
+  text-align: center;
+}
+
+/* Results cards */
+.gr-output-html {
+  background: white !important;
+  border-radius: calc(var(--border-radius) - 0.2rem) !important;
+  padding: var(--spacing-sm) !important;
+  box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.08);
+  min-height: 6rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+}
+
+/* Error styling */
+#errors_group {
+  background: var(--light-red);
+  border: 1px solid var(--warning-red);
+  border-radius: var(--border-radius);
+  padding: var(--spacing-md);
+  margin-top: var(--spacing-md);
+}
+
+/* Responsive layout */
+@media (max-width: 768px) {
+  #outputsContainer .gr-row {
+    flex-direction: column;
+  }
+
+  #confCol,
+  #speciesCol,
+  #edibilityCol {
+    margin-bottom: var(--spacing-sm);
+  }
+}
+
+/* Dark mode adjustments */
+.dark #inputsContainer,
+.dark #outputsContainer {
+  background: #1e1e1e;
+}
+
+.dark .gr-output-html {
+  background: #2d2d2d !important;
+  color: var(--text-light) !important;
+}
+
+.output-card {
+  width: fit-content;
+}
+
+/* Confidence Display */
+.confidence-display {
+  background: white;
+  border-radius: 12px;
+  padding: 1.5rem;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+  margin-bottom: 1.5rem;
+}
+
+.confidence-header {
+  display: flex;
+  align-items: center;
+  margin-bottom: 1rem;
+  gap: 0.75rem;
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: #2e7d32;
+}
+
+.confidence-icon {
+  font-size: 1.5rem;
+}
+
+.confidence-visual {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-bottom: 0.75rem;
+}
+
+.confidence-bar-bg {
+  flex-grow: 1;
+  height: 1.5rem;
+  background: #e0e0e0;
+  border-radius: 10px;
+  overflow: hidden;
+}
+
+.confidence-bar-fill {
+  height: 100%;
+  background: linear-gradient(90deg, #4caf50, #8bc34a);
+  border-radius: 10px;
+  transition: width 0.5s ease-in-out;
+}
+
+.confidence-value {
+  min-width: 3.5rem;
+  font-weight: 700;
+  font-size: 1.25rem;
+  text-align: center;
+  color: #2e7d32;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .confidence-header {
+    font-size: 1.1rem;
+  }
+
+  .confidence-visual {
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+
+  .confidence-bar-bg {
+    width: 100%;
+  }
+
+  .confidence-value {
+    align-self: flex-end;
+  }
+}
+
+#bottomLine {
+  height: 0.9px;
+}