Perfume Pal

Perfume Pal is an AI powered scent designer that turns your vibe and ingredients into ready to mix, personalized perfume oil recipes on Cloud Run.

Comment

Inspiration

Perfume prices keep going up, people are increasingly suspicious of the ingredients in commercial fragrances, and there is a growing desire to have a unique personal scent instead of smelling like every designer counter. I started my own perfume oil brand, Akhdar Perfumes, and saw firsthand that beginners can create great blends if they just have good guidance. Perfume Pal was built to give them exactly that - making it easy for anyone to design their own perfume oils at home, even with zero experience.

What it does

Perfume Pal is an AI-powered web application that transforms vague scent preferences into concrete, ready-to-mix perfume recipes. Users describe what they want:

  • Scent style (dark oud, fresh citrus, sweet gourmand, etc.)
  • Fragrance strength (subtle, moderate, or strong)
  • Bottle size in milliliters
  • Available ingredients (optional) like oud, sandalwood, vanilla, or bergamot

When the user clicks Generate Formula, Perfume Pal calls a multi-agent workflow running on Google Cloud Run. Behind the scenes, two specialized AI agents built with Google's Agent Development Kit and powered by Gemini collaborate:

Agent 1: Scent Planner takes the user's text and turns it into a structured brief containing the target profile, note families, number of recipes to generate, and constraints like "prefer user ingredients" or "avoid overly sweet."

Agent 2: Formula Architect uses that brief to create actual perfume oil recipes. For each recipe it generates:

  • A name and description
  • Top, heart, and base notes classification
  • A list of ingredients with percentages and approximate drop counts for the chosen bottle size
  • Simple mixing instructions
  • A safety note reminding users to patch test

The Cloud Run service returns this JSON to the frontend, and the UI renders it as easy-to-follow cards that users can screenshot or print and take straight to their mixing table.

How we built it

Technology Stack:

  • Backend: FastAPI running on Google Cloud Run, exposing a simple /api/generate_blends endpoint
  • Frontend: Lightweight HTML, CSS, and vanilla JavaScript calling that endpoint
  • AI Architecture: Multi-agent workflow using Google ADK with two Gemini-powered agents (Scent Planner and Formula Architect)
  • Deployment: Docker containerization for Cloud Run
  • API Integration: Google Generative AI SDK with gemini-flash-latest model

Development Process: The application is built around a clean separation of concerns. The frontend collects user preferences through an intuitive form interface with a tech-inspired design featuring an intro screen, navigation between Designer and About sections, and animated UI elements. When the user submits their preferences, the FastAPI backend validates the input using Pydantic models and triggers the multi-agent workflow.

The Scent Planner agent analyzes the user's preferences and creates a structured perfume brief with specific note families, intensity levels, and formulation constraints. This brief is then passed to the Formula Architect agent, which generates detailed recipes following real perfumery principles - proper top/heart/base note proportions, realistic ingredient combinations, and practical mixing instructions.

The agents use Gemini's JSON mode (response_mime_type="application/json") to ensure structured, parseable outputs. We implemented robust error handling with regex-based fallback parsing to handle any edge cases in the AI responses.

Challenges we ran into

Gemini API Model Naming: Initially used outdated model names that weren't available in the v1beta API. Discovered available models using genai.list_models() and switched to gemini-flash-latest.

JSON Parsing Reliability: Gemini sometimes returned malformed JSON or wrapped responses in markdown code blocks. Solved by using response_mime_type="application/json" for strict JSON output and implementing regex-based JSON extraction as a fallback.

Environment Variable Configuration: The agents needed API keys at initialization time, but environment variables weren't always set in the server process. Fixed by having agents configure the API within their initialization methods.

Multi-Agent Coordination: Ensuring the Scent Planner's output was structured correctly for the Formula Architect to consume required careful prompt engineering and schema design.

Accomplishments that we're proud of

  • Built a fully functional multi-agent AI system using Google ADK and Gemini that actually generates practical, mixable perfume recipes
  • Deployed successfully to Google Cloud Run with proper environment configuration and health checks
  • Created two specialized AI agents that collaborate seamlessly - turning vague preferences like "I want a smoky oud for winter" into concrete formulations
  • Designed a modern tech-inspired UI with intro screen, navigation, and comprehensive about section
  • Achieved sub-second response times for recipe generation
  • Made perfume creation accessible to anyone, regardless of experience level
  • Applied real perfumery knowledge (from running Akhdar Perfumes) to validate AI outputs

What we learned

  • Google ADK simplifies multi-agent workflows - the structure makes it easy to chain specialized AI agents, each focused on one part of the problem
  • Gemini's JSON mode is production-ready - structured outputs with proper schemas produce consistent, reliable results
  • Cloud Run is ideal for AI applications - serverless scaling handles variable AI response times gracefully without infrastructure management
  • Prompt engineering makes the difference - specific prompts with clear JSON schemas and real perfumery constraints produce better results than generic requests
  • Multi-agent systems outperform single prompts - breaking the task (understanding preferences then generating formulas) into specialized agents produces more accurate, nuanced results

What's next for Perfume Pal

  • Production Cloud Run Deployment with custom domain and SSL
  • User Accounts and History to save favorite recipes and preferences
  • Ingredient Database Integration connecting to real essential oil suppliers for purchasing
  • Mobile Application using React Native for iOS and Android
  • Additional AI Agents for safety checks, allergen warnings, and cost calculations
  • Community Features where users can share recipes, rate formulations, and discover creations from others
  • AI-Powered Scent Matching where users upload photos or describe occasions and get personalized recommendations
  • Batch Processing to generate multiple variations of a recipe at once

Built With

Share this project:

Updates