| | --- |
| | title: Min StyleMatch AI |
| | emoji: 📉 |
| | colorFrom: gray |
| | colorTo: green |
| | sdk: gradio |
| | sdk_version: 5.33.1 |
| | app_file: app.py |
| | pinned: false |
| | license: apache-2.0 |
| | short_description: LLM-Powered Styling & Color Analysis via MCP Server + Gradio |
| | tags: |
| | - Agents-MCP-Hackathon |
| | - agent-demo-track |
| | - mcp-server-track |
| | --- |
| | |
| | # Project Name: Min-StyleMatch AI – LLM-Powered Styling & Color Analysis via MCP Server + Gradio Client |
| |
|
| | --- |
| | ## 🎬 Demo Video |
| |
|
| | [](https://www.youtube.com/watch?v=VvRdsgGUVJQ) |
| |
|
| | --- |
| | ## 📚 Table of Contents |
| |
|
| | - [🧠 Project Overview](#-project-overview) |
| | - [🔧 Tools Integrated](#-tools-integrated) |
| | - [⚠️ Project Status](#️-note-this-project-is-not-production-ready) |
| | - [🔍 Models Used](#-models-used) |
| | - [📦 Open-Source Models (via Nebius)](#-open-source-models-via-nebius) |
| | - [🔐 Closed-Source Models (via OpenAI)](#-closed-source-models-via-openai) |
| | - [🧩 System Architecture Overview](#-system-architecture-overview) |
| | - [🚀 Quickstart](#-quickstart) |
| | - [🔐 Your Data & Privacy](#-your-data--privacy) |
| | - [🧠 Chat History](#-chat-history) |
| | - [🖼️ Image Handling](#️-image-handling) |
| | - [🎨 Facial Color Data](#-facial-color-data) |
| | - [✅ Dataset Overview](#-dataset-overview) |
| | - [🔄 Data Processing Steps](#-data-processing-steps) |
| | - [📦 Output](#-output) |
| |
|
| | --- |
| |
|
| | ## 🧠 Project Overview |
| |
|
| | This project uses **FastMCP** for custom **MCP (Model Context Protocol)** server and a **Gradio Chatbot** as an **MCP Client**, designed to demonstrate how Language Models (LLMs) can interact with tools for advanced reasoning and personalization. |
| |
|
| | ### 🔧 Tools Integrated |
| |
|
| | 1. **🧑💻 Developer Info Tool** |
| |
|
| | * Returns information about the developer (you). |
| | * Purpose: Demonstrates how **MCP tool calling** supports **prompt decomposition**, allowing the LLM to delegate parts of the task to improve response accuracy and structure. |
| |
|
| | 2. **🛍️ Product Filtering Tool** |
| |
|
| | * Connects the LLM with product data stored in `.csv` files (used as a lightweight database). |
| | * Purpose: Showcases how LLMs can support **product recommendation systems** by filtering based on user preferences, color suitability, or product attributes. |
| |
|
| | 3. **🎨 Color Season Analysis Tool** |
| |
|
| | * Operates in an **Agent-based setup** using two LLMs: |
| |
|
| | * One extracts **facial feature colors** (e.g., skin, eyes, hair, lips) from a user-uploaded image. |
| | * The second uses this data to predict the **user’s color season**. |
| | * Purpose: Demonstrates **multi-model collaboration**, improving accuracy by separating image understanding from season classification. |
| | *(Combining both steps into one model often resulted in inconsistent or random outputs.)* |
| | |
| | --- |
| |
|
| | > ⚠️ **Note:** This project is **not production-ready**. |
| | > It is a **demo prototype** built to: |
| | > |
| | > * Showcase how to integrate product data with LLMs using **tool calling**. |
| | > * Demonstrate **multi-model collaboration** (e.g., using image and text models in tandem). |
| | > * Illustrate **prompt decomposition** and how MCP (Model Context Protocol) enables modular reasoning through tool-based workflows. |
| | > |
| | > While functional, the current version has **non-optimized system flow**, **basic tool logic**, and **initial prompt configurations**. |
| | > These areas can be significantly improved for better performance, scalability, and production-readiness. |
| | > |
| | > This project is intended as a **learning resource** and a practical starting point for **junior developers**, **LLM enthusiasts**, or teams exploring how to combine AI tools with real-world datasets. |
| | > |
| | > With future iterations—such as improved orchestration, tighter prompt design, and scalable backend architecture—it can evolve into a robust, intelligent personalization system. |
| |
|
| | --- |
| |
|
| | ## 🔍 Models Used |
| |
|
| | ### 📦 Open-Source Models (via Nebius) |
| |
|
| | * **Qwen2.5-VL-72B-Instruct** – For visual-linguistic processing. |
| | * **Mistral-Nemo-Instruct-2407** – For general instruction-following tasks. |
| |
|
| | ### 🔐 Closed-Source Models (via OpenAI) |
| |
|
| | * **GPT-4o-mini** *(primary for tool-calling)* |
| | * **GPT-4.1-mini** |
| |
|
| | > ⚠️ *Note:* Currently, only OpenAI models are used for **tool calling**, as their API is more mature and familiar. |
| | > I have not explored whether **Nebius supports tool calling**. |
| |
|
| | --- |
| | ## 🧩 System Architecture Overview |
| |
|
| | ```mermaid |
| | graph TD |
| | User["🧑 User"] |
| | Gradio["🤖 Gradio MCP Client"] |
| | FastMCP["🛠️ FastMCP Server"] |
| | Tool1["🧑💻 Developer Info Tool"] |
| | Tool2["🛍️ Product Filter Tool"] |
| | Tool3["🎨 Color Season Tool"] |
| | LLM["🧠 LLM (OpenAI / Nebius)"] |
| | |
| | User --> Gradio |
| | Gradio --> FastMCP |
| | FastMCP --> Tool1 |
| | FastMCP --> Tool2 |
| | FastMCP --> Tool3 |
| | Tool3 --> LLM |
| | Tool1 --> LLM |
| | Tool2 --> LLM |
| | ``` |
| |
|
| | --- |
| | ## 🚀 Quickstart |
| |
|
| | 1. **Clone the repository** |
| | ```bash |
| | git clone https://github.com/yourusername/stylematch-assistant.git |
| | cd stylematch-assistant |
| | pip install -r requirements.txt |
| | ``` |
| |
|
| | --- |
| |
|
| | ## 🔐 Your Data & Privacy |
| |
|
| | This project requires the use of the **OpenAI API** and optionally the **Nebius AI Studio API**. All API keys are **encrypted** and **never exposed in plain text**. |
| |
|
| | This is a **demo project**, and for your safety and control, I recommend cloning the repository and running it locally on your machine. |
| |
|
| | ### 🧠 Chat History |
| |
|
| | * Your conversation is **not stored permanently**. |
| | * Chat history will be **cleared** if you **refresh the browser** or **close the session**. |
| |
|
| | ### 🖼️ Image Handling |
| |
|
| | * When you upload a face image, it is stored **temporarily** for analysis. |
| | * If you're **inactive** or stop interacting with the assistant, the image will be **automatically deleted**. |
| | * No facial image is permanently saved. |
| |
|
| | ### 🎨 Facial Color Data |
| |
|
| | * The extracted **skin, hair, eyes, lips colors**, and your **color season result** are handled just like your image—**temporary and private**. |
| | * This information is only used to **enhance your personalized experience** and is **not retained** after your session ends. |
| |
|
| | --- |
| |
|
| | ## ✅ Dataset Overview |
| | This project uses the [Fashion Product Images Dataset](https://www.kaggle.com/datasets/paramaggarwal/fashion-product-images-dataset) from Kaggle, which contains metadata and image filenames for over 44,000 fashion products. |
| |
|
| | The dataset consists of two key files: |
| |
|
| | * **`styles.csv`** – contains product metadata such as category, gender, and usage. |
| | * **`images.csv`** – contains filenames of product images, linked to the product via the `id` column. |
| |
|
| |
|
| | ### 🔄 Data Processing Steps |
| |
|
| | The function `load_combined_dataset(styles_path, images_path)` performs the following operations: |
| |
|
| | 1. **Load CSV Files** |
| |
|
| | * Reads `styles.csv` and `images.csv`. |
| | * Skips malformed lines automatically to avoid read errors. |
| |
|
| | 2. **Prepare for Merge** |
| |
|
| | * Cleans the `filename` column in `images.csv` by stripping `.jpg` and converting it into integer `id` for merging. |
| |
|
| | 3. **Data Cleaning** |
| |
|
| | * Drops all rows with missing (`NaN`) values from both DataFrames. |
| | * Merges the two DataFrames on the `id` column using an inner join. |
| | * Ensures the resulting combined dataset has no null values. |
| |
|
| | 4. **Filter Relevant Categories** |
| |
|
| | * Since this is a demo, I keeps only the products that belong to **Apparel** or **Footwear** categories (ignores others such as Accessories). |
| |
|
| | ### 📦 Output |
| |
|
| | The function returns a cleaned and filtered `pandas.DataFrame` containing only products ready for personalized styling and analysis. |
| |
|
| | --- |
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
