Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+captured_images
+.git
+.gitignore

.env.example

@@ -0,0 +1,20 @@
+# Groq API Credentials (for LLM Agents)
+GROQ_API_KEY=your_groq_api_key_here
+# Model to use (defaults to llama-3.1-8b-instant if not set; llama-3.3-70b-versatile is also supported but has lower free-tier rate limits)
+GROQ_MODEL=llama-3.1-8b-instant
+
+# ChromaDB Cloud Credentials
+CHROMA_API_KEY=your_chroma_api_key_here
+
+# Supabase — inventory database
+SUPABASE_URL=https://<your-project-ref>.supabase.co
+SUPABASE_ANON_KEY=your_supabase_anon_key_here
+
+# Object Detection (YOLOv8n ONNX) — crops detected objects before CLIP
+ENABLE_OBJECT_DETECTION=false
+YOLO_MODEL_ID=ultralytics/yolov8n
+YOLO_MODEL_FILENAME=yolov8n.onnx
+DETECTION_CONFIDENCE_THRESHOLD=0.25
+DETECTION_IOU_THRESHOLD=0.45
+MAX_DETECTIONS=3
+CROP_PADDING_RATIO=0.10

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+.env

Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.10-slim
+
+WORKDIR /code
+
+# Install system dependencies (needed for standard operations if any)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY ./requirements.txt /code/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+COPY . .
+
+# Hugging Face Spaces runs on port 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,43 @@
 ---
-title: Fast Api Cloud
-emoji: 📊
-colorFrom: gray
-colorTo: indigo
+title: AIShoppingAssistance Server
+emoji: 🔥
+colorFrom: indigo
+colorTo: green
 sdk: docker
 pinned: false
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Current Directory Structure for the Server
+```
+hf_server/
+├── app/
+│   ├── __init__.py              # Python package marker
+│   ├── main.py                  # Main entrypoint (FastAPI, Middlewares, Routers, and lifespans)
+│   ├── config.py                # Server & model configuration constants
+│   ├── models/                  # Pydantic schemas / request-response models
+│   │   ├── __init__.py
+│   │   └── recipe.py            # Pydantic model for recipes
+│   ├── services/                # Heavy logic & external database clients
+│   │   ├── __init__.py
+│   │   ├── http_client.py       # Global HTTPX AsyncClient lifecycle
+│   │   ├── detector.py          # CLIP/ONNX model and embedding generation
+│   │   ├── chroma.py            # ChromaDB Searcher
+│   │   └── supabase.py          # Supabase Querier
+│   ├── routes/                  # API endpoints
+│   │   ├── __init__.py
+│   │   ├── health.py            # health and root paths
+│   │   ├── detection.py         # product detection, embeddings, and gallery
+│   │   └── recipe.py            # recipe generation and cart agent
+│   └── agents/                  # AI agents & parser logic
+│       ├── __init__.py
+│       ├── shopping_assistant_agent.py # Main conversational agentic loop
+│       ├── recipe_agent.py      # Recipe agent orchestrator
+│       └── tools/               # Agent tools
+│           ├── __init__.py
+│           └── quantity_parser_tool.py # Quantity measurement parser
+├── requirements.txt
+├── Dockerfile                  # Updated entrypoint cmd
+└── run_local.sh
+```

app/__init__.py

@@ -0,0 +1 @@
+# App package initialization

app/agents/__init__.py

@@ -0,0 +1 @@
+# Agents package initialization

app/agents/missing_regulars_agent.py

@@ -0,0 +1,192 @@
+import os
+import json
+import statistics
+from datetime import datetime
+from typing import List, Dict, Any
+from groq import Groq
+from dotenv import load_dotenv
+
+from app.services.supabase import SupabaseQuerier
+
+base_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+dotenv_path = os.path.join(base_dir, ".env")
+load_dotenv(dotenv_path=dotenv_path, override=True)
+
+class MissingRegularsAgent:
+    def __init__(self):
+        api_key = os.getenv("GROQ_API_KEY")
+        if api_key:
+            api_key = api_key.replace("your_groq_api_key_here", "").strip()
+        print(f"[MissingRegularsAgent] GROQ API Key: {api_key}")
+        if not api_key:
+            print("[WARNING] GROQ_API_KEY not detected, using mock key")
+            api_key = "gsk_mock_key_placeholder"
+        self.client = Groq(api_key=api_key)
+        self.model = os.getenv("GROQ_MODEL", "llama-3.1-8b-instant")
+        self.fallback_model = os.getenv("GROQ_FALLBACK_MODEL", "llama-3.3-70b-versatile")
+        self.supabase = SupabaseQuerier()
+
+    def _analyze_regularity(self, orders: List[Dict[str, Any]], current_cart_skus: List[str]) -> List[Dict[str, Any]]:
+        """
+        Analyzes order history to find regular items missing from the current cart.
+        Applies a 3-layer filter: Frequency, Consistency (CV), and Timing (Due Date).
+        """
+        if not orders:
+            return []
+
+        # 1. Extract dates and group by SKU
+        sku_history = {}
+        sku_metadata = {}
+
+        for order in orders:
+            try:
+                # The items column might be a JSON string or already parsed list
+                items_raw = order.get("items", [])
+                items = json.loads(items_raw) if isinstance(items_raw, str) else items_raw
+                
+                # Parse created_at
+                created_at_str = order.get("created_at")
+                if not created_at_str:
+                    continue
+                # Simple parsing assuming ISO format
+                created_at = datetime.fromisoformat(created_at_str.replace("Z", "+00:00")).date()
+
+                for item in items:
+                    # Extract SKU from details if id is not the SKU
+                    details = item.get("details", "")
+                    sku = item.get("id")
+                    if "SKU: " in details:
+                        sku = details.split("SKU: ")[1].split(" ")[0]
+
+                    if not sku:
+                        continue
+
+                    if sku not in sku_history:
+                        sku_history[sku] = set()
+                        sku_metadata[sku] = {
+                            "sku": sku,
+                            "name": item.get("name", "Unknown Item"),
+                            "price": item.get("price", 0),
+                            "imageUrl": item.get("imageUrl", "")
+                        }
+                    
+                    sku_history[sku].add(created_at)
+
+            except Exception as e:
+                print(f"[MissingRegularsAgent] Error parsing order: {e}")
+                continue
+
+        today = datetime.utcnow().date()
+        missing_regulars = []
+
+        # 2. Apply regularity logic
+        for sku, dates_set in sku_history.items():
+            dates = sorted(list(dates_set))
+            
+            # Layer 1: Frequency Check (Must be bought on at least 3 distinct days)
+            if len(dates) < 3:
+                continue
+
+            # Calculate gaps between purchases
+            gaps = [(dates[i] - dates[i-1]).days for i in range(1, len(dates))]
+            if not gaps:
+                continue
+
+            avg_gap = statistics.mean(gaps)
+            
+            # Layer 2: Consistency Check (CV <= 0.6)
+            if len(gaps) > 1:
+                std_dev = statistics.stdev(gaps)
+                cv = std_dev / avg_gap if avg_gap > 0 else 0
+                if cv > 0.6:
+                    continue # Too erratic, not a consistent regular item
+
+            # Layer 3: Timing / Due Date Check
+            days_since_last = (today - dates[-1]).days
+            
+            # If they bought it very recently, they don't need it yet.
+            # If days_since_last is close to or greater than avg_gap, they are due.
+            # We add a small buffer (e.g., -2 days) so we remind them slightly before they completely run out.
+            if days_since_last < (avg_gap - 2):
+                continue
+
+            # Final Filter: Is it already in the cart?
+            if sku in current_cart_skus:
+                continue
+
+            # Passed all layers! It's a missing regular.
+            item_data = sku_metadata[sku]
+            item_data["frequency"] = len(dates)
+            item_data["avg_gap_days"] = round(avg_gap, 1)
+            item_data["last_bought_days_ago"] = days_since_last
+            
+            missing_regulars.append(item_data)
+
+        # Sort by most frequently bought
+        missing_regulars.sort(key=lambda x: x["frequency"], reverse=True)
+        return missing_regulars
+
+    async def analyze_cart(self, user_id: str, current_cart: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Main entry point for the route.
+        Fetches history, finds missing regulars, and gets the LLM to write a friendly reminder.
+        """
+        # Fetch history (last 90 days)
+        orders = await self.supabase.get_order_history(user_id=user_id, days=90)
+        
+        # Extract current SKUs
+        current_skus = [item.get("sku") or item.get("id") for item in current_cart]
+        
+        # Find missing regulars via Python logic
+        missing_items = self._analyze_regularity(orders, current_skus)
+        
+        if not missing_items:
+            return {
+                "response_text": "",
+                "missing_regulars": []
+            }
+
+        # Format items for the LLM prompt
+        cart_str = ", ".join([item.get("name", "") for item in current_cart]) if current_cart else "Empty cart"
+        missing_str = ", ".join([item["name"] for item in missing_items])
+
+        # LLM writes the phrasing
+        prompt = f"""You are a helpful, friendly AI shopping assistant.
+The user is currently reviewing their shopping cart.
+Current cart contains: {cart_str}
+
+Based on our deterministic analysis of their past 90 days of orders, they regularly buy these items every few weeks, but forgot to add them today:
+Missing Regulars: {missing_str}
+
+Write a very brief, friendly 1-2 sentence reminder suggesting they might want to add these to their cart before checking out. 
+Do not mention the "90 days" or the algorithm. Just be natural and helpful, like "I noticed you usually grab..." or "Don't forget your usual...".
+Respond ONLY with the message text. No JSON, no extra formatting."""
+
+        try:
+            try:
+                completion = self.client.chat.completions.create(
+                    model=self.model,
+                    messages=[{"role": "user", "content": prompt}],
+                    max_tokens=150,
+                    temperature=0.4
+                )
+            except Exception as inner_e:
+                if self.fallback_model:
+                    print(f"[MissingRegularsAgent] Main model {self.model} failed: {inner_e}. Falling back to {self.fallback_model}...")
+                    completion = self.client.chat.completions.create(
+                        model=self.fallback_model,
+                        messages=[{"role": "user", "content": prompt}],
+                        max_tokens=150,
+                        temperature=0.4
+                    )
+                else:
+                    raise inner_e
+            response_text = completion.choices[0].message.content.strip()
+        except Exception as e:
+            print(f"[MissingRegularsAgent] LLM Generation failed completely: {e}")
+            response_text = "It looks like you might have forgotten a few of your regular items. Would you like to add them?"
+
+        return {
+            "response_text": response_text,
+            "missing_regulars": missing_items
+        }

app/agents/recipe_agent.py

@@ -0,0 +1,468 @@
+import os
+import json
+import re
+from typing import Dict, Any, List
+from groq import Groq
+from dotenv import load_dotenv
+from app.services.nutrition_service import NutritionService
+from app.services.quantity_normalizer_service import QuantityNormalizerService
+
+# Explicitly load .env file from the hf_server directory
+base_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+dotenv_path = os.path.join(base_dir, ".env")
+load_dotenv(dotenv_path=dotenv_path, override=True)
+
+# Hard Category Guardrail: substrings that identify non-cooking items
+# (household cleaners, air fresheners, baby formulas, health drinks, etc.)
+# Items matching any of these in their name or slug are excluded from the
+# inventory before the LLM ever sees them.
+_NON_FOOD_SUBSTRINGS = [
+    "air freshener", "air-freshener", "car air freshener",
+    "room spray", "room-spray",
+    "cleaner", "disinfectant", "flushmatic",
+    "shampoo", "hair colour", "water bottle", "water-bottle",
+    "cerelac", "ceregrow", "lactogen", "similac",
+    "health drink", "health-drink", "horlicks", "bournvita",
+    "power pocket", "power-pocket",
+]
+
+class RecipeAgent:
+    def __init__(self):
+        api_key = os.getenv("GROQ_API_KEY")
+        if api_key:
+            api_key = api_key.replace("your_groq_api_key_here", "").strip()
+        if not api_key:
+            print("[WARNING] GROQ_API_KEY not detected, using mock key")
+            api_key = "gsk_mock_key_placeholder_for_verification_only"
+        self.client = Groq(api_key=api_key)
+        self.model = os.getenv("GROQ_MODEL", "llama-3.1-8b-instant")
+        self.nutrition_service = NutritionService()
+        self.quantity_normalizer = QuantityNormalizerService(
+            os.getenv("USDA_API_KEY")
+        )
+        self.fallback_model = os.getenv("GROQ_FALLBACK_MODEL", "llama-3.3-70b-versatile")
+
+    def _clean_dish_name(self, query: str) -> str:
+        q = str(query).lower().strip()
+        
+        # Strip common punctuation
+        q = re.sub(r"[?.,!]", "", q)
+        
+        # Regex replacement patterns for common recipe request prefixes
+        prefixes = [
+            r"\bgive me the recipe for a\b",
+            r"\bgive me the recipe for an\b",
+            r"\bgive me the recipe for\b",
+            r"\bgive me a recipe for\b",
+            r"\brecipe for a\b",
+            r"\brecipe for an\b",
+            r"\brecipe for\b",
+            r"\bhow to make a\b",
+            r"\bhow to make an\b",
+            r"\bhow to make\b",
+            r"\bhow to cook a\b",
+            r"\bhow to cook an\b",
+            r"\bhow to cook\b",
+            r"\bhow do i make a\b",
+            r"\bhow do i make an\b",
+            r"\bhow do i make\b",
+            r"\bhow do i cook a\b",
+            r"\bhow do i cook an\b",
+            r"\bhow do i cook\b",
+            r"\bi want to make a\b",
+            r"\bi want to make an\b",
+            r"\bi want to make\b",
+            r"\bi want a recipe for\b",
+        ]
+        
+        for pattern in prefixes:
+            q = re.sub(pattern, "", q).strip()
+            
+        # Capitalize words to make it look premium
+        return q.title()
+
+    def _create_chat_completion(self, messages, max_tokens=1024, temperature=0.2, response_format=None):
+        try:
+            return self.client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                response_format=response_format
+            )
+        except Exception as e:
+            if self.fallback_model:
+                print(f"⚠️ [RECIPE AGENT FALLBACK] Main model {self.model} failed: {e}. Falling back to {self.fallback_model}...")
+                return self.client.chat.completions.create(
+                    model=self.fallback_model,
+                    messages=messages,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    response_format=response_format
+                )
+            else:
+                raise e
+
+
+    async def generate(self, dish_query: str, servings: int) -> Dict[str, Any]:
+        """
+        Generates a detailed recipe using Groq forced output structures.
+        """
+        clean_dish = self._clean_dish_name(dish_query)
+        prompt = f"""Generate a detailed recipe for {clean_dish} for {servings} servings.
+        IMPORTANT:
+- quantity must be a NUMBER only.
+- Never include units inside quantity.
+- Correct:
+  quantity: 1, unit: "cups"
+  quantity: 2, unit: "tablespoons"
+  quantity: 3, unit: "cloves"
+- Incorrect:
+  quantity: "1 cup"
+  quantity: "2 tablespoons"
+  quantity: "3 cloves"
+### CRITICAL INGREDIENT ISOLATION RULES:
+
+1. Every ingredient must be a single USDA-searchable ingredient.
+2. Never group multiple ingredients into one ingredient.
+3. Never use parentheses in ingredient names.
+4. Never include preparation details in ingredient names.
+
+BAD:
+- Vegetables (carrots, peas, cauliflower)
+- Spices (cumin, coriander, turmeric)
+- Rice (washed and soaked)
+- Onion (thinly sliced)
+
+GOOD:
+- Mixed Vegetables
+- Spices
+- Rice
+- Onion
+- Garlic
+- Ginger
+
+Ingredient names must be simple, singular, USDA-searchable names.
+Preparation details belong in recipe instructions, not ingredient names.
+
+Return ONLY valid JSON in this exact format (no markdown strings, no code fences):
+{{
+  "dish": "{clean_dish}",
+  "servings": {servings},
+  "instructions": ["step 1", "step 2"],
+  "ingredients": [
+    {{"name": "Ingredient Name", "quantity": "amount", "unit": "unit"}}
+  ]
+}}
+
+CRITICAL RULE — Ingredient Isolation: Every single ingredient must be its own independent dictionary entry in the "ingredients" list. NEVER group multiple items together in a single line like "Spices (Turmeric, Salt, Chili Powder)". Break them down into separate entries: {{"name": "Turmeric Powder", "quantity": "1/2", "unit": "teaspoon"}}, {{"name": "Red Chili Powder", ...}}, and {{"name": "Salt", ...}}."""
+
+        messages = [
+            {
+                "role": "system", 
+                "content": "You are an expert chef assistant. You must provide your output strictly formatted as a json object matching the structural schema requested."
+            },
+            {"role": "user", "content": prompt}
+        ]
+
+        response = self._create_chat_completion(
+            messages=messages,
+            max_tokens=1024,
+            temperature=0.2,
+            response_format={"type": "json_object"}
+        )
+
+        content = response.choices[0].message.content or ""
+        content = content.strip().removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+
+        try:
+            return json.loads(content)
+
+        except json.JSONDecodeError:
+            return {
+                "raw_response": content,
+                "dish": clean_dish,
+                "servings": servings,
+                "instructions": [],
+                "ingredients": []
+            }
+
+    def _is_non_food(self, item: Dict[str, Any]) -> bool:
+        """Category guardrail: check if an inventory item is a non-cooking item
+        (household cleaner, air freshener, baby food, health drink, etc.)"""
+        text = (item.get("name", "") + " " + item.get("slug", "")).lower()
+        return any(sub in text for sub in _NON_FOOD_SUBSTRINGS)
+
+    def _filter_relevant_inventory(self, parsed_ingredients: List[Dict[str, Any]], inventory_catalog: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Pre-filter inventory to only items whose name/slug shares tokens with ingredient names.
+        Then apply Category Guardrail to drop non-cooking items entirely.
+        This prevents the LLM from seeing completely unrelated items (e.g. toilet cleaner
+        alongside spices) and hallucinating matches."""
+        candidates = []
+        seen = set()
+
+        # Sauce/condiment guardrail: prevent condiment products (sauce, ketchup, jam, spread)
+        # from matching raw ingredients that don't mention the condiment category.
+        # e.g. "Sweet Onion Sauce" must NOT match "Onion" — sauce != raw vegetable.
+        # "paste" is intentionally excluded since pastes (Ginger Garlic Paste) are valid ingredient matches.
+        sauce_keywords = {"sauce", "ketchup", "jam", "spread"}
+
+        for ing in parsed_ingredients:
+            ing_name = ing.get("name", "").lower().strip()
+            # Clean out common leakage remnants that survived parsing
+            ing_name = re.sub(r"\bas needed\b|\binch piece\b", "", ing_name).strip()
+
+            # Split into tokens: keep 3+ char words, plus short staples like "ghee"
+            ing_tokens = [t for t in ing_name.split() if len(t) >= 3 or t == "ghee"]
+
+            if not ing_tokens and not ing_name:
+                continue
+
+            for item in inventory_catalog:
+                # Category Guardrail: skip non-food items entirely
+                if self._is_non_food(item):
+                    continue
+
+                item_name = item.get("name", "").lower()
+                item_slug = item.get("slug", "").lower()
+
+                # Sauce Guardrail: if the item is a condiment and the ingredient is not, skip
+                if any(sk in item_name for sk in sauce_keywords) and not any(sk in ing_name for sk in sauce_keywords):
+                    continue
+
+                # Broad containment matching: token in name/slug, or full name in item name
+                if any(token in item_name or token in item_slug for token in ing_tokens) or ing_name in item_name:
+                    key = item.get("sku") or item.get("slug", "")
+                    if key not in seen:
+                        seen.add(key)
+                        candidates.append(item)
+
+        # If filtering removed everything, return what we have rather than
+        # randomly padding with unrelated food items (which causes hallucinated
+        # matches like "Quaker Oats" appearing in a pizza ingredient list).
+        return candidates
+
+    def match_inventory_with_ai(self, parsed_ingredients: List[Dict[str, Any]], inventory_catalog: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Uses Groq to intelligently map parsed ingredients to real store catalog items.
+        """
+        filtered_catalog = self._filter_relevant_inventory(parsed_ingredients, inventory_catalog)
+
+        prompt = f"""
+        You are a strict retail inventory matching system. Your job is to look at each requested recipe ingredient's "name" field and find a semantically equivalent product from our store inventory.
+
+        Requested Recipe Ingredients (only the "name" field matters for matching):
+        {json.dumps(parsed_ingredients, indent=2)}
+
+        Our Store Inventory Catalog (only relevant products shown):
+        {json.dumps(filtered_catalog, indent=2)}
+
+        ### CRITICAL MATCHING RULES:
+        1. The product MUST BE the actual ingredient, not just share a word. Examples of BAD matches you must NEVER do:
+           - Ingredient "Onions" → "Cream and Onion Chips" (chips are NOT onions)
+           - Ingredient "Rice" → "Cerelac Rice" (baby cereal is NOT cooking rice)
+           - Ingredient "Ginger" → "Chocolate Bar" (chocolate is NOT ginger)
+           - Ingredient "Garlic" → "Wheat Apple Baby Food" (baby food is NOT garlic)
+           - Ingredient "Oil" → "Tomato Ketchup" (ketchup is NOT oil)
+           - Ingredient "Spices" → "Air Freshener" (air freshener is NOT a spice)
+
+        2. Only match when the product IS the ingredient (e.g., "Oil" → "Groundnut Oil", "Milk" → "Standardised Milk", "Ginger" or "Garlic" → "Ginger Garlic Paste").
+
+        3. If no truly matching product exists in inventory, you MUST return "sku": "UNKNOWN", "price_rupees": 0, "slug": the ingredient name as a lowercase-slug, "name": the ingredient name. In this case, you should also look at the inventory catalog and provide up to 3 possible close substitutes that are available in the inventory under the "substitutes" key. For example, if "Heavy Cream" is requested and not found, you can suggest "Standardised Milk" or "Butter" as substitutes. If no substitutes are reasonable, return an empty list.
+
+        4. The "required_quantity" field should use the ingredient's "quantity" value from the requested ingredient (or "raw_input").
+
+        ### Expected Output Format:
+        Return a strict JSON object with a single key "results" containing an array of matched items:
+        {{
+          "results": [
+            {{
+              "sku": "string",
+              "slug": "string",
+              "name": "string",
+              "price_rupees": number,
+              "required_quantity": "string",
+              "substitutes": [
+                {{
+                  "sku": "string",
+                  "name": "string",
+                  "price_rupees": number,
+                  "thumbnail_url": "string"
+                }}
+              ]
+            }}
+          ]
+        }}
+        """
+
+        completion = self._create_chat_completion(
+            messages=[
+                {
+                    "role": "system",
+                    "content": "You are a strict inventory matching assistant. Never match an ingredient to a product that is not the actual ingredient. Only match when the product IS the ingredient (e.g. oil to oil, milk to milk). If no match exists, return UNKNOWN. If an ingredient is UNKNOWN, identify up to 3 suitable substitute items from the inventory catalog and place them in the \"substitutes\" list. Return only a valid JSON object with a \"results\" key."
+                },
+                {
+                    "role": "user",
+                    "content": prompt
+                }
+            ],
+            response_format={"type": "json_object"}
+        )
+
+        try:
+            result = json.loads(completion.choices[0].message.content)
+            # Handle if AI nests it inside a root dictionary key wrapper
+            if isinstance(result, dict):
+                for key in ["matches", "items", "data", "ingredients", "results"]:
+                    if key in result:
+                        return result[key]
+                return list(result.values())[0] if result else []
+            return result
+        except Exception:
+            return []
+
+    async def generate_and_match_recipe(self, dish_query: str, servings: int, inventory_catalog: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Generates a detailed recipe and matches its ingredients to the store catalog in a single LLM call.
+        """
+        clean_dish = self._clean_dish_name(dish_query)
+        food_catalog = [item for item in inventory_catalog if not self._is_non_food(item)]
+
+        prompt = f"""Generate a detailed recipe for {clean_dish} for {servings} servings, and match the required ingredients to our store's inventory catalog.
+
+Available Store Inventory Catalog (SKUs and Names):
+{json.dumps(food_catalog, indent=2)}
+
+### CRITICAL MATCHING RULES:
+1. Every single recipe ingredient must be matched to a product in the catalog.
+2. The product MUST BE the actual ingredient, not just share a word. Examples of BAD matches:
+   - "Onions" -> "Cream and Onion Chips" (chips are NOT onions)
+   - "Rice" -> "Cerelac Rice" (baby cereal is NOT cooking rice)
+   - "Garlic" -> "Wheat Apple Baby Food"
+   - "Oil" -> "Tomato Ketchup"
+   - "Flour" or any pizza ingredient -> "Quaker Oats" (oats are NOT a pizza ingredient)
+   - "Cheese" or "Dough" -> "Oats" or "Cereal" (breakfast items are NOT pizza/bread ingredients)
+3. Only match when the product IS the ingredient (e.g. "Oil" -> "Gold Winner Refined Sunflower Oil" or "Idhayam Mantra Groundnut Oil", "Milk" -> "Amul Gold Standardised Milk", "Ginger" or "Garlic" -> "Aachi Ginger Garlic Paste").
+4. If no truly matching product exists in the catalog, you MUST return "sku": "UNKNOWN", "price_rupees": 0, "name": the ingredient name, and "slug": the ingredient name as a lowercase-slug.
+
+For UNKNOWN items, only provide substitutes if they are the same type of cooking ingredient.
+
+Examples:
+- Oil -> another oil product
+- Milk -> another milk product
+- Ginger Garlic Paste -> another cooking paste
+- Rice -> another rice product
+
+Never suggest cereals, chocolates, chips, sweets, beverages, breakfast foods, baby foods, or instant noodles as substitutes for vegetables, rice, spices, meat, dairy, flour, dough, or cooking ingredients.
+
+If no closely related cooking ingredient exists in the catalog, return an empty list for "substitutes".
+### CRITICAL INGREDIENT ISOLATION RULES:
+
+- Every ingredient must be a single USDA-searchable ingredient.
+- Never group multiple ingredients into one ingredient.
+- Never use parentheses in ingredient names.
+- Never include preparation details in ingredient names.
+
+BAD:
+- Vegetables (carrots, peas, cauliflower)
+- Spices (cumin, coriander, turmeric)
+- Rice (washed and soaked)
+- Onion (thinly sliced)
+
+GOOD:
+- Mixed Vegetables
+- Spices
+- Rice
+- Onion
+- Garlic
+- Ginger
+
+Ingredient names must be simple USDA-searchable names.
+Preparation details belong in recipe instructions, not ingredient names.
+
+IMPORTANT:
+- quantity must be a NUMBER only.
+- Never include units inside quantity.
+
+Correct:
+quantity: 2, unit: "cups"
+quantity: 1, unit: "teaspoon"
+
+Incorrect:
+quantity: "2 cups"
+quantity: "1 teaspoon"
+Return ONLY valid JSON in this exact format (no markdown strings, no code fences):
+{{
+  "dish": "{clean_dish}",
+  "servings": {servings},
+  "instructions": ["step 1", "step 2"],
+  "ingredients": [
+    {{
+      "name": "Ingredient Name",
+      "quantity": 1,
+      "unit": "unit",
+      "sku": "SKU_CODE_IF_MATCHED_OR_UNKNOWN",
+      "slug": "product-slug",
+      "price_rupees": 0.0,
+      "substitutes": [
+        {{
+          "sku": "string",
+          "name": "string",
+          "price_rupees": 0.0
+        }}
+      ]
+    }}
+  ]
+}}
+"""
+
+        messages = [
+            {
+                "role": "system",
+                "content": "You are an expert chef and a strict retail inventory matching system. You must generate recipes and match the ingredients strictly to the available catalog products, returning only a valid JSON object matching the requested schema."
+            },
+            {"role": "user", "content": prompt}
+        ]
+
+        response = self._create_chat_completion(
+            messages=messages,
+            max_tokens=1536,
+            temperature=0.2,
+            response_format={"type": "json_object"}
+        )
+
+        content = response.choices[0].message.content or ""
+        content = content.strip().removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+
+        try:
+            result = json.loads(content)
+            print("\n===== RAW RECIPE INGREDIENTS =====")
+            for x in result.get("ingredients", []):
+                print(x)
+            print("=================================\n")
+            async with self.quantity_normalizer as normalizer:
+                normalized_ingredients, skipped = (
+                    await normalizer.normalize_ingredients(
+                        result.get("ingredients", [])
+                    )
+                )
+
+            print("NORMALIZED:", normalized_ingredients)
+            print("SKIPPED:", skipped)
+
+            nutrition = await self.nutrition_service.calculate_recipe_nutrition(
+                normalized_ingredients,
+                result.get("servings", servings),
+            )
+            print("NUTRITION RESULT:", nutrition)
+
+            result["nutrition"] = nutrition
+
+            return result
+        except json.JSONDecodeError:
+            return {
+                "dish": clean_dish,
+                "servings": servings,
+                "instructions": [],
+                "ingredients": []
+            }

app/agents/recipe_parser.py

@@ -0,0 +1,115 @@
+import re
+
+class RecipeParser:
+    BAD_WORDS = [
+        "facebook",
+        "instagram",
+        "youtube",
+        "pinterest",
+        "twitter",
+        "share",
+        "recipe",
+        "faq",
+        "faqs",
+        "tips",
+        "comments",
+        "jump",
+        "about"
+    ]
+
+    def _clean_text(self, text: str) -> str:
+        text = re.sub(r'\[(.*?)\]\([^)]*\)', r'\1', text)
+        text = re.sub(r'\*\*|__|~~', '', text)
+        text = text.replace('•', '-').strip()
+        text = re.sub(r'\s+', ' ', text)
+        return text.strip()
+
+    def _is_markdown_link(self, text: str) -> bool:
+        return bool(re.match(r'^\[.*\]\(.*\)$', text))
+
+    def _should_skip(self, text: str) -> bool:
+        cleaned = self._clean_text(text).lower()
+        if not cleaned:
+            return True
+        if self._is_markdown_link(cleaned):
+            return True
+        if any(word in cleaned for word in self.BAD_WORDS):
+            return True
+        return False
+
+    def extract_servings(self, markdown: str) -> int:
+        """
+        Extract serving count from recipe markdown.
+        
+        Looks for patterns like:
+        - Serves 4
+        - Servings: 4
+        - Yield: 4
+        - Makes 4 servings
+        
+        Args:
+            markdown (str): Recipe markdown content
+            
+        Returns:
+            int: Number of servings, defaults to 1 if not found
+        """
+        if not markdown:
+            return 1
+        
+        # Search in the first 2000 characters to find metadata
+        text = markdown[:2000].lower()
+        
+        # Pattern 1: "serves 4" or "serve 4"
+        match = re.search(r'serves?\s+(\d+)', text)
+        if match:
+            return int(match.group(1))
+        
+        # Pattern 2: "servings: 4" or "serving: 4"
+        match = re.search(r'servings?\s*:\s*(\d+)', text)
+        if match:
+            return int(match.group(1))
+        
+        # Pattern 3: "yield: 4"
+        match = re.search(r'yields?\s*:\s*(\d+)', text)
+        if match:
+            return int(match.group(1))
+        
+        # Pattern 4: "makes 4 servings" or "make 4 servings"
+        match = re.search(r'makes?\s+(\d+)', text)
+        if match:
+            return int(match.group(1))
+        
+        return 1
+
+    def parse(self, markdown: str):
+        ingredients = []
+        instructions = []
+
+        for line in markdown.splitlines():
+            raw = line.strip()
+            if not raw:
+                continue
+
+            normalized = self._clean_text(raw)
+            if not normalized or self._should_skip(raw):
+                continue
+
+            if re.match(r'^(ingredients?|shopping list)\s*:?', normalized, re.IGNORECASE):
+                continue
+
+            if re.match(r'^[-*]\s+', raw):
+                item = re.sub(r'^[-*]\s+', '', raw)
+                item = self._clean_text(item)
+                if item and not self._should_skip(item):
+                    ingredients.append(item)
+
+            elif re.match(r'^\d+[.)]\s+', raw):
+                item = re.sub(r'^\d+[.)]\s+', '', raw)
+                item = self._clean_text(item)
+                if item and not self._should_skip(item):
+                    instructions.append(item)
+
+        return {
+            "ingredients": ingredients,
+            "instructions": instructions
+        }

app/agents/shopping_assistant_agent.py

@@ -0,0 +1,1052 @@
+import json
+import os
+import asyncio
+from typing import List, Dict, Any
+from groq import Groq
+from dotenv import load_dotenv
+from app.agents.recipe_agent import RecipeAgent
+from app.agents.tools.quantity_parser_tool import QuantityParserTool
+from app.services.nutrition_service import NutritionService
+
+# Explicitly load .env file from the hf_server directory
+base_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+dotenv_path = os.path.join(base_dir, ".env")
+load_dotenv(dotenv_path=dotenv_path, override=True)
+
+from app.utils.cart_state import live_cart_memory
+
+# ─── UPDATED REAL TOOL FUNCTION ───
+def execute_database_cart_addition(user_id: str, sku: str, quantity: int) -> bool:
+    """
+    Directly writes a persistent modification entry to your application's 
+    active shopping cart storage cache layer.
+    """
+    success = live_cart_memory.add_item(user_id=user_id, sku=sku, quantity=quantity)
+    if success:
+        print(f"💾 [STATE COMMIT] User: '{user_id}' | SKU: '{sku}' successfully written to memory.")
+    return success
+
+def execute_database_cart_removal(user_id: str, sku: str, quantity: int) -> bool:
+    """
+    Directly writes a persistent modification entry to remove or decrement a SKU in the cart.
+    """
+    success = live_cart_memory.remove_item(user_id=user_id, sku=sku, quantity=quantity)
+    if success:
+        print(f"💾 [STATE REMOVE] User: '{user_id}' | SKU: '{sku}' successfully removed/decremented from memory.")
+    return success
+
+# ─── ACTIVE REGISTRY MANDATORY HOOK ───
+ACTIVE_CART_TOOLS_REGISTRY = {
+    "add_to_cart": execute_database_cart_addition,
+    "remove_from_cart": execute_database_cart_removal
+}
+
+def format_ingredient_quantity(quantity: Any, unit: Any) -> str:
+    """
+    Formats the quantity and unit of an ingredient safely, avoiding duplication
+    such as "1 cup cup" or "1 cup cup flour".
+    """
+    qty_str = str(quantity or "").strip()
+    unit_str = str(unit or "").strip()
+    
+    if not unit_str:
+        return qty_str
+    if not qty_str:
+        return unit_str
+        
+    # Check if the unit string is already present in quantity or vice versa
+    if unit_str.lower() in qty_str.lower():
+        return qty_str
+    if qty_str.lower() in unit_str.lower():
+        return unit_str
+        
+    # Word-level comparison to prevent e.g. "1 cup" and "cups" -> "1 cup cups"
+    qty_words = qty_str.split()
+    if qty_words:
+        last_word = qty_words[-1]
+        
+        def clean_word(w):
+            w = w.lower().strip(".,() ")
+            if w.endswith("es"):
+                w = w[:-2]
+            elif w.endswith("s"):
+                w = w[:-1]
+            return w
+            
+        if clean_word(last_word) == clean_word(unit_str):
+            return qty_str
+            
+    return f"{qty_str} {unit_str}"
+
+def _parse_qty(qty_str: Any) -> int:
+    """
+    Parses a human-readable quantity string into an integer for cart additions.
+    Examples: "2 cans" -> 2, "1.5 cups" -> 2, "3" -> 3, "half" -> 1, "" -> 1
+    """
+    import re
+    if not qty_str:
+        return 1
+    s = str(qty_str).strip().lower()
+    # Handle textual fractions
+    word_map = {"half": 1, "one": 1, "two": 2, "three": 3, "four": 4, "five": 5}
+    for word, val in word_map.items():
+        if s.startswith(word):
+            return val
+    match = re.match(r"(\d+(?:\.\d+)?)", s)
+    if match:
+        return max(1, round(float(match.group(1))))
+    return 1
+
+def clean_ingredient_name(name: Any, unit: Any) -> str:
+    """
+    Cleans the ingredient name by removing any prepended unit words.
+    E.g. name="cups All-purpose flour", unit="cups" -> "All-purpose flour"
+    E.g. name="teaspoons Active dry yeast", unit="teaspoons" -> "Active dry yeast"
+    """
+    name_str = str(name or "").strip()
+    unit_str = str(unit or "").strip()
+    if not name_str or not unit_str:
+        return name_str
+        
+    name_words = name_str.split()
+    if not name_words:
+        return name_str
+        
+    first_word = name_words[0]
+    
+    # Exact word match (case-insensitive)
+    if first_word.lower() == unit_str.lower():
+        cleaned = " ".join(name_words[1:]).strip()
+        if cleaned.lower().startswith("of "):
+            cleaned = cleaned[3:].strip()
+        return cleaned
+        
+    # Singular/plural matched word comparison
+    def clean_word(w):
+        w = w.lower().strip(".,() ")
+        if w.endswith("es"):
+            w = w[:-2]
+        elif w.endswith("s"):
+            w = w[:-1]
+        return w
+        
+    if clean_word(first_word) == clean_word(unit_str):
+        cleaned = " ".join(name_words[1:]).strip()
+        if cleaned.lower().startswith("of "):
+            cleaned = cleaned[3:].strip()
+        return cleaned
+        
+    return name_str
+
+class ShoppingAssistantAgent:
+    def __init__(self):
+        api_key = os.getenv("GROQ_API_KEY")
+        if api_key:
+            api_key = api_key.replace("your_groq_api_key_here", "").strip()
+        if not api_key:
+            print("[WARNING] GROQ_API_KEY not detected in environment, using mock key to prevent startup crash")
+            api_key = "gsk_mock_key_placeholder_for_verification_only"
+        self.client = Groq(api_key=api_key)
+        self.model = os.getenv("GROQ_MODEL", "llama-3.1-8b-instant")
+        self.fallback_model = os.getenv("GROQ_FALLBACK_MODEL", "llama-3.3-70b-versatile")
+        self.recipe_agent = RecipeAgent()
+        self.quantity_parser = QuantityParserTool()
+        self.nutrition_service = NutritionService()
+        self.inventory = self._load_inventory()
+
+    def _load_inventory(self) -> List[Dict[str, Any]]:
+        """Loads the store inventory catalog from candidate locations."""
+        base_dir = os.path.dirname(os.path.abspath(__file__))
+        candidates = [
+            "/workspaces/AIShoppingAssistance/inventory.json",
+            os.path.abspath(os.path.join(base_dir, "inventory.json")),
+            os.path.abspath(os.path.join(base_dir, "..", "inventory.json")),
+            os.path.abspath(os.path.join(base_dir, "..", "..", "inventory.json")),
+            os.path.abspath(os.path.join(base_dir, "..", "..", "..", "inventory.json")),
+            os.path.abspath(os.path.join(base_dir, "..", "..", "..", "..", "inventory.json")),
+            os.path.abspath("inventory.json"),
+            os.path.abspath("../inventory.json"),
+        ]
+        
+        inventory_path = None
+        for path in candidates:
+            if os.path.exists(path):
+                inventory_path = path
+                break
+                
+        if not inventory_path:
+            inventory_path = os.path.abspath(os.path.join(base_dir, "..", "..", "inventory.json"))
+
+        try:
+            with open(inventory_path, "r") as f:
+                data = json.load(f)
+                return data.get("items", data) if isinstance(data, dict) else data
+        except Exception as e:
+            print(f"⚠️ [WARNING] Failed to load inventory database catalog from {inventory_path}: {e}")
+            return []
+
+    # ── Stopwords to strip before keyword matching ──
+    _STOP_WORDS = {
+        "a", "an", "the", "is", "are", "do", "you", "have", "has", "me", "my",
+        "i", "to", "of", "for", "in", "on", "at", "and", "or", "but", "can",
+        "it", "this", "that", "what", "how", "where", "which", "with", "your",
+        "add", "get", "show", "give", "want", "buy", "some", "any", "please",
+        "tell", "like", "make", "under", "over", "than", "more", "less", "much",
+        "many", "very", "just", "also", "from", "about", "would", "could", "should",
+    }
+
+    def _prefetch_relevant_items(self, query: str) -> List[Dict[str, Any]]:
+        """
+        Regex-extract meaningful keywords from the user query, run token
+        matching against the inventory, and return the top matches with full
+        details (name, SKU, price).  Called before the first LLM request so
+        the LLM can answer price/detail questions without an extra
+        search_inventory round-trip.
+        """
+        import re
+
+        # ── Category-word → inventory-token expansion ──────────────────────
+        _CATEGORY_MAP = {
+            "snack":     ["chocolate", "chips", "biscuit", "cookie", "wafer", "bar", "candy", "cracker"],
+            "snacks":    ["chocolate", "chips", "biscuit", "cookie", "wafer", "bar", "candy", "cracker"],
+            "drink":     ["drink", "juice", "milk", "water", "coffee", "tea", "energy"],
+            "drinks":    ["drink", "juice", "milk", "water", "coffee", "tea", "energy"],
+            "noodle":    ["noodles", "maggi", "instant", "cuppa"],
+            "noodles":   ["noodles", "maggi", "instant", "cuppa"],
+            "breakfast": ["cereal", "oats", "milk", "bread", "egg", "muesli"],
+            "chocolate": ["chocolate", "cocoa", "dark"],
+            "biscuit":   ["biscuit", "cookie", "digestive", "cream"],
+            "biscuits":  ["biscuit", "cookie", "digestive", "cream"],
+            "chips":     ["chips", "crisps", "namkeen", "rings", "puffs"],
+            "sauce":     ["sauce", "ketchup", "chutney", "paste"],
+        }
+
+        # ── Extract price ceiling from query (e.g. "under ₹50", "below 100") ──
+        price_ceiling = None
+        price_match = re.search(r"(?:under|below|less\s+than|within)\s*[₹rs\.]*\s*(\d+)", query.lower())
+        if price_match:
+            price_ceiling = int(price_match.group(1))
+
+        # Lowercase, strip punctuation, tokenise
+        cleaned = re.sub(r"[^\w\s]", " ", query.lower())
+        raw_tokens = [t for t in cleaned.split() if len(t) >= 3 and t not in self._STOP_WORDS]
+
+        # Expand category words
+        expanded_tokens = list(raw_tokens)
+        for t in raw_tokens:
+            if t in _CATEGORY_MAP:
+                expanded_tokens.extend(_CATEGORY_MAP[t])
+
+        if not expanded_tokens:
+            return []
+
+        matches: List[tuple] = []
+        for item in self.inventory:
+            item_name   = item.get("name", "").lower()
+            item_slug   = item.get("slug", "").lower()
+            item_tokens = set(item_name.split() + item_slug.split("-"))
+            score = sum(1 for t in expanded_tokens if t in item_tokens)
+            # Exact substring bonus for original (non-expanded) tokens
+            for t in raw_tokens:
+                if t in item_name:
+                    score += 2
+            if score > 0:
+                matches.append((item, score))
+
+        matches.sort(key=lambda x: x[1], reverse=True)
+        top = [item for item, _ in matches[:20]]
+
+        # Apply price filter if detected
+        if price_ceiling is not None:
+            top = [it for it in top if it.get("price_rupees", 9999) <= price_ceiling]
+
+        return top[:12]
+
+
+    # ── Regex-based recipe intent classifier (no LLM needed) ──────────────
+    _RECIPE_PATTERNS = [
+        r"\b(recipe|recipes)\b",
+        r"\bhow\s+(?:do\s+(?:i|we)|to|can\s+(?:i|we))\s+(?:make|cook|prepare|bake|fry|boil|roast|grill)\b",
+        r"\b(?:steps?|instructions?|procedure)\s+(?:to|for)\s+(?:make|cook|prepare)\b",
+        r"\b(?:make|cook|prepare|bake)\s+(?:me\s+)?(?:a|an|some)?\s*\w+\s+(?:dish|meal|curry|biryani|dosa|roti|bread|cake|soup|salad|pasta|noodle)\b",
+        r"\bingredients\s+(?:for|to\s+make)\b",
+        r"\bwhat\s+(?:do\s+i\s+need|ingredients)\s+(?:for|to\s+(?:make|cook))\b",
+    ]
+
+    def _is_recipe_query(self, query: str) -> bool:
+        """Pure-regex recipe intent check — no LLM call needed."""
+        import re
+        q = query.lower()
+        return any(re.search(p, q) for p in self._RECIPE_PATTERNS)
+
+
+    def tool_search_inventory(self, query: str) -> List[Dict[str, Any]]:
+        """Search the store inventory for products matching the query."""
+        query_lower = query.lower().strip()
+        ing_tokens = set(t for t in query_lower.split() if len(t) >= 3 or t in ["ghee", "oil"])
+        
+        matches = []
+        for item in self.inventory:
+            item_name = item.get("name", "").lower()
+            item_slug = item.get("slug", "").lower()
+            
+            # Simple scoring
+            item_tokens = set(item_name.split() + item_slug.split("-"))
+            score = len(ing_tokens.intersection(item_tokens))
+            if query_lower in item_name or item_name in query_lower:
+                score += 5
+                
+            if score > 0:
+                matches.append((item, score))
+                
+        # Sort by score descending
+        matches.sort(key=lambda x: x[1], reverse=True)
+        return [item for item, score in matches[:10]]
+
+    def tool_add_to_cart(self, user_id: str, sku: str, quantity: int = 1, mutations: List[Dict[str, Any]] = None) -> str:
+        # Find item details
+        item = next((x for x in self.inventory if x.get("sku") == sku), None)
+        if not item:
+            return f"Error: SKU '{sku}' not found in inventory."
+            
+        success = execute_database_cart_addition(user_id, sku, quantity)
+        if success and mutations is not None:
+            mutations.append({
+                "action": "add",
+                "sku": sku,
+                "name": item.get("name"),
+                "price": float(item.get("price_rupees", 0.0)),
+                "quantity": quantity,
+                "thumbnail_url": item.get("thumbnail_url", "")
+            })
+        return f"Successfully added {quantity} x '{item.get('name')}' (SKU: {sku}) to the cart."
+
+    def tool_remove_from_cart(self, user_id: str, sku: str, quantity: int = 1, mutations: List[Dict[str, Any]] = None) -> str:
+        item = next((x for x in self.inventory if x.get("sku") == sku), None)
+        if not item:
+            return f"Error: SKU '{sku}' not found in inventory."
+            
+        success = execute_database_cart_removal(user_id, sku, quantity)
+        if success and mutations is not None:
+            mutations.append({
+                "action": "remove",
+                "sku": sku,
+                "name": item.get("name"),
+                "price": float(item.get("price_rupees", 0.0)),
+                "quantity": quantity
+            })
+        return f"Successfully removed/decremented {quantity} x '{item.get('name')}' (SKU: {sku}) from the cart."
+
+    def tool_clear_cart(self, user_id: str, mutations: List[Dict[str, Any]] = None) -> str:
+        live_cart_memory.clear_cart(user_id)
+        if mutations is not None:
+            mutations.append({
+                "action": "clear"
+            })
+        return "Successfully cleared all items from the cart."
+
+    async def _generate_and_match_recipe_internal(self, user_id: str, current_cart_slugs: List[str], dish_query: str, servings: int) -> Dict[str, Any]:
+        """
+        Generates the recipe and runs matching against catalog.
+        This contains the original process_recipe_workflow implementation.
+        """
+        try:
+            toxic_keywords = {"cleaner", "harpic", "lizol", "toilet", "disinfectant", "floor", "soap"}
+            processed_keywords = {"cerelac", "boost", "horlicks", "bournvita", "baby", "cereal", "chocos"}
+            sauce_keywords = {"sauce", "ketchup", "paste", "jam", "spread"}
+            snack_keywords = {"chips", "lays", "kurkure", "namkeen", "biscuit", "cookie", "bingo"}
+            utility_keywords = {"bottle", "flask", "container", "jar", "box", "spoon", "knife", "pan"}
+            
+            query_lower = dish_query.lower()
+            if any(tk in query_lower for tk in toxic_keywords):
+                print(f"🛑 [SECURITY BLOCK] Malicious payload injection caught in query: '{dish_query}'")
+                return {
+                    "dish": str(dish_query),
+                    "servings": int(servings),
+                    "recipe_instructions": ["Recipe blocked due to safety violations."],
+                    "parsed_ingredients": [],
+                    "missing_ingredients": [],
+                    "cart_additions": []
+                }
+            
+            # 1. Generate and match recipe in a single LLM call
+            recipe_result = await self.recipe_agent.generate_and_match_recipe(dish_query, servings, self.inventory)
+            
+            instructions_list = recipe_result.get("instructions", [])
+            ingredients = recipe_result.get("ingredients", [])
+
+            missing_ingredients_map = {}
+            cart_additions_map = {}
+
+            # Build two lookup sets for robust deduplication:
+            # 1. Normalized slugs (strip apostrophes/special chars Flutter adds)
+            # 2. SKU set from current_cart (authoritative — immune to slug drift)
+            import re as _re
+            def _norm_slug(s: str) -> str:
+                return _re.sub(r"[^a-z0-9\-]", "", str(s).lower().strip())
+
+            normalized_cart_slugs = [_norm_slug(slug) for slug in (current_cart_slugs or [])]
+            # current_cart_slugs are name-derived — also build a SKU set from current_cart
+            # NOTE: _generate_and_match_recipe_internal only receives cart_slugs, not
+            # the full current_cart. For now use the live_cart_memory which was just
+            # synced from Flutter as the SKU source of truth.
+            from app.utils.cart_state import live_cart_memory as _cart_mem
+            synced_skus = set(_cart_mem.get_cart(user_id).keys())
+
+            # Parse and compose the final missing ingredients and cart additions lists
+            for ing in ingredients:
+                ing_name = clean_ingredient_name(ing.get("name", ""), ing.get("unit", ""))
+                ing_name_lower = ing_name.lower().strip()
+                ing_sku = ing.get("sku", "UNKNOWN")
+                
+                # Deduplicate slug format
+                ing_slug = ing.get("slug", ing_name_lower.replace(" ", "-")).lower().strip()
+                if not ing_slug:
+                    ing_slug = ing_name_lower.replace(" ", "-")
+
+                if _norm_slug(ing_slug) in normalized_cart_slugs:
+                    continue
+
+                final_qty = format_ingredient_quantity(ing.get('quantity'), ing.get('unit'))
+
+                if ing_sku != "UNKNOWN":
+                    # Look up actual item from catalog to resolve name, slug, price, and thumbnail_url
+                    actual_item = next((item for item in self.inventory if item.get("sku") == ing_sku), None)
+                    if actual_item:
+                        item_sku = actual_item.get("sku")
+                        item_slug = actual_item.get("slug", ing_slug).lower().strip()
+                        
+                        if item_sku in synced_skus or _norm_slug(item_slug) in normalized_cart_slugs:
+                            continue
+
+                        if item_sku in missing_ingredients_map:
+                            missing_ingredients_map[item_sku]["required_quantity"] += f" + {final_qty}"
+                            missing_ingredients_map[item_sku]["quantity"] = missing_ingredients_map[item_sku].get("quantity", 0) + _parse_qty(final_qty)
+                        else:
+                            missing_ingredients_map[item_sku] = {
+                                "sku": item_sku,
+                                "slug": item_slug,
+                                "name": actual_item.get("name"),
+                                "price_rupees": float(actual_item.get("price_rupees", 0.0)),
+                                "thumbnail_url": actual_item.get("thumbnail_url", ""),
+                                "required_quantity": final_qty,
+                                "quantity": _parse_qty(final_qty),
+                                "agent_tool_status": "Committed to DB"
+                            }
+                        
+                        if item_sku in cart_additions_map:
+                            cart_additions_map[item_sku]["quantity"] += _parse_qty(final_qty)
+                        else:
+                            cart_additions_map[item_sku] = {
+                                "sku": item_sku,
+                                "name": actual_item.get("name"),
+                                "price": float(actual_item.get("price_rupees", 0.0)),
+                                "quantity": _parse_qty(final_qty)
+                            }
+                else:
+                    # Clean up substitute list if any (ensure thumbnail URLs from inventory match if applicable)
+                    cleaned_subs = []
+                    for sub in ing.get("substitutes", []):
+                        sub_sku = sub.get("sku")
+                        if sub_sku:
+                            actual_sub = next((item for item in self.inventory if item.get("sku") == sub_sku), None)
+                            if actual_sub:
+                                cleaned_subs.append({
+                                    "sku": sub_sku,
+                                    "name": actual_sub.get("name"),
+                                    "price_rupees": float(actual_sub.get("price_rupees", 0.0)),
+                                    "thumbnail_url": actual_sub.get("thumbnail_url", "")
+                                })
+                            else:
+                                cleaned_subs.append(sub)
+                        else:
+                            cleaned_subs.append(sub)
+
+                    missing_ingredients_map[ing_slug] = {
+                        "sku": "UNKNOWN",
+                        "slug": ing_slug,
+                        "name": ing_name,
+                        "price_rupees": 0.0,
+                        "thumbnail_url": "",
+                        "required_quantity": final_qty,
+                        "quantity": _parse_qty(final_qty),
+                        "substitutes": cleaned_subs
+                    }
+
+            return {
+                "dish": str(dish_query),
+                "servings": int(servings),
+                "instructions": list(instructions_list),
+                "recipe_instructions": list(instructions_list),
+                "ingredients": [
+                    {
+                        "name": clean_ingredient_name(ing.get("name", ""), ing.get("unit", "")),
+                        "quantity": format_ingredient_quantity(ing.get("quantity"), ing.get("unit"))
+                    }
+                    for ing in ingredients
+                ],
+                "parsed_ingredients": [],
+                "missing_ingredients": list(missing_ingredients_map.values()),
+                "cart_additions": list(cart_additions_map.values())
+            }
+            
+        except Exception as e:
+            import traceback
+            print("❌ [CRITICAL PIPELINE EXCEPTION]")
+            traceback.print_exc()
+            return {"error": str(e), "missing_ingredients": [], "cart_additions": []}
+
+    async def process_recipe_workflow(
+        self,
+        user_id: str = "anonymous_user",
+        current_cart_slugs: List[str] = None,
+        dish_query: str = "",
+        servings: int = 2,
+        chat_history: List[Dict[str, Any]] = None,
+        current_cart: List[Dict[str, Any]] = None,
+        image_base64: str = None
+    ) -> Dict[str, Any]:
+        generator = self.process_recipe_workflow_stream(
+            user_id=user_id,
+            current_cart_slugs=current_cart_slugs,
+            dish_query=dish_query,
+            servings=servings,
+            chat_history=chat_history,
+            current_cart=current_cart,
+            image_base64=image_base64
+        )
+        full_text = ""
+        recipe_data = None
+        mutations = None
+        llm_unavailable = False
+        async for chunk_str in generator:
+            if not chunk_str.strip():
+                continue
+            try:
+                chunk = json.loads(chunk_str.strip())
+                if chunk.get("llm_unavailable"):
+                    llm_unavailable = True
+                elif "text_chunk" in chunk:
+                    full_text += chunk["text_chunk"]
+                else:
+                    if "recipe" in chunk:
+                        recipe_data = chunk["recipe"]
+                    if "cart_mutations" in chunk:
+                        mutations = chunk["cart_mutations"]
+            except Exception as parse_err:
+                print(f"Error parsing generator chunk: {parse_err}")
+        # Handle case where the LLM may have output a JSON wrapper (legacy behavior)
+        response_text = full_text.strip()
+        if response_text.startswith('{'):
+            try:
+                parsed = json.loads(response_text)
+                if isinstance(parsed, dict) and "response_text" in parsed:
+                    response_text = parsed["response_text"]
+            except Exception:
+                pass  # Not JSON, use as-is
+        
+        return {
+            "response_text": response_text,
+            "recipe": recipe_data,
+            "cart_mutations": mutations,
+            "llm_unavailable": llm_unavailable
+        }
+
+    async def process_recipe_workflow_stream(
+        self,
+        user_id: str = "anonymous_user",
+        current_cart_slugs: List[str] = None,
+        dish_query: str = "",
+        servings: int = 2,
+        chat_history: List[Dict[str, Any]] = None,
+        current_cart: List[Dict[str, Any]] = None,
+        image_base64: str = None
+    ):
+        mutations: List[Dict[str, Any]] = []
+        recipe_data = None
+
+        # Format current cart details
+        cart_details_str = "No items in cart."
+        if current_cart:
+            cart_details_str = "\n".join([
+                f"- {item.get('name', 'Unknown')} (Quantity: {item.get('quantity', 1)}, SKU: {item.get('sku', 'UNKNOWN')})"
+                for item in current_cart
+            ])
+        elif current_cart_slugs:
+            cart_details_str = "\n".join([
+                f"- {slug} (Quantity: 1)"
+                for slug in current_cart_slugs
+            ])
+
+        # ── Pre-fetch relevant inventory items for this query ──────────────
+        prefetched_items: List[Dict[str, Any]] = []
+        if dish_query and not image_base64:
+            prefetched_items = self._prefetch_relevant_items(dish_query)
+
+        # ── Fast-path: if clearly a recipe query, skip LLM tool-call round-trip ──
+        if dish_query and not image_base64 and self._is_recipe_query(dish_query):
+            print(f"🍳 [RECIPE FAST-PATH] Detected recipe intent in: {dish_query!r}")
+            recipe_data = await self._generate_and_match_recipe_internal(
+                user_id=user_id,
+                current_cart_slugs=current_cart_slugs,
+                dish_query=dish_query,
+                servings=servings
+            )
+            yield json.dumps({"text_chunk": f"Here's your recipe for {dish_query}! I've matched the ingredients to our store catalog. Check the recipe card below."}) + "\n"
+            yield json.dumps({"cart_mutations": mutations if mutations else None, "recipe": recipe_data}) + "\n"
+            return
+
+        # Format the catalog details for system prompt
+        # When prefetch found relevant items, use those (with price) instead of the full catalog
+        # to save tokens. Fall back to full catalog for open-ended or greeting queries.
+        catalog_str = "No items in catalog."
+        if self.inventory:
+            if prefetched_items:
+                catalog_str = (
+                    "(Showing items most relevant to this query — full catalog available via search_inventory tool)\n"
+                    + "\n".join(
+                        f"- Name: {it.get('name')} | SKU: {it.get('sku')} | Price: ₹{it.get('price_rupees', '?')}"
+                        for it in prefetched_items
+                    )
+                )
+            else:
+                catalog_str = "\n".join([
+                    f"- Name: {item.get('name')} | SKU: {item.get('sku')}"
+                    for item in self.inventory
+                ])
+
+        
+        tools_definitions = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "search_inventory",
+                    "description": "Search the store inventory for products matching the query term. Returns items with SKU, name, price, and slug.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string",
+                                "description": "The search term to look for in the catalog (e.g. 'snickers', 'milk', 'eggs')."
+                            }
+                        },
+                        "required": ["query"]
+                    }
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "add_to_cart",
+                    "description": "Add a specific product to the user's cart by its SKU.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "sku": {
+                                "type": "string",
+                                "description": "The SKU of the product to add."
+                            },
+                            "quantity": {
+                                "type": "integer",
+                                "description": "The quantity to add.",
+                                "default": 1
+                            }
+                        },
+                        "required": ["sku"]
+                    }
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "remove_from_cart",
+                    "description": "Remove or decrement a product from the user's cart by its SKU.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "sku": {
+                                "type": "string",
+                                "description": "The SKU of the product to remove/decrement."
+                            },
+                            "quantity": {
+                                "type": "integer",
+                                "description": "The quantity to remove/decrement.",
+                                "default": 1
+                            }
+                        },
+                        "required": ["sku"]
+                    }
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "generate_and_match_recipe",
+                    "description": "Generate a cooking recipe for a SPECIFIC dish name (e.g. 'pasta', 'veg biryani'). DO NOT call this tool for general shopping recommendations, breakfast item suggestions, snacks, greetings, or conversational questions.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "dish_name": {
+                                "type": "string",
+                                "description": "The name of the specific dish to generate a recipe for (e.g., 'Tomato Soup'). Do NOT pass general queries or lists here."
+                            },
+                            "servings": {
+                                "type": "integer",
+                                "description": "The number of servings.",
+                                "default": 2
+                            }
+                        },
+                        "required": ["dish_name"]
+                    }
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "clear_cart",
+                    "description": "ONLY call this tool when the user EXPLICITLY requests to clear, empty, or wipe their entire cart (e.g. 'clear my cart', 'empty my cart', 'remove all items', 'start fresh'). NEVER call this tool when the user wants to ADD items, REMOVE a specific item, or asks about the cart. Calling this tool destroys the entire cart, so it must be used with extreme caution.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {}
+                    }
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "get_nutrition_info",
+                    "description": "Fetch real nutritional details (calories, protein, carbs, fats per 100g) for a single raw food or catalog product name from the USDA FoodData Central database. Use this tool when the user asks for nutritional facts, calorie counts, or macro information of specific foods.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "item_query": {
+                                "type": "string",
+                                "description": "The exact food or ingredient name to query (e.g. 'Standardised Milk', 'Egg', 'Oats', 'Apple')."
+                            }
+                        },
+                        "required": ["item_query"]
+                    }
+                }
+            }
+        ]
+
+        messages = [
+            {
+                "role": "system",
+                "content": f"""You are the Qless Assistant, an intelligent, conversational AI retail and cooking assistant for the Qless self-checkout store.
+You help users with shopping suggestions, chitchat, cooking recipe inquiries, and real-time cart modifications.
+
+Active User ID: {user_id}
+
+Current Cart Items:
+{cart_details_str}
+
+*IMPORTANT NOTE ON CART STATE*: The "Current Cart Items" list above is the absolute, authoritative truth of what is currently in the user's cart. Any past requests in the chat history (e.g., "add 4 items") have already been fully executed and are already included in the list above. Refer only to the list above to know what is in the cart.
+- Even if a product name mentioned in the chat history (e.g., "Cadbury Fuse") is slightly different from the name in the "Current Cart Items" list (e.g., "Cadbury Fuse Chocolate Bar"), they refer to the same item and you must NOT sum their quantities. The quantity in the "Current Cart Items" list is the ONLY quantity in the cart.
+- Any item mentioned in the chat history that is NOT in the "Current Cart Items" list above has been removed and is NO LONGER in the cart. Do NOT list it or assume it is still in the cart.
+- Do NOT sum, add, or double-count quantities from the chat history with the list above.
+
+⚠️ CRITICAL — STALE CART DATA IN HISTORY: The chat history you receive may contain old assistant responses that listed cart contents (e.g., "Current Cart Items: Lays x5"). These are SNAPSHOTS of a PAST state and are ALWAYS WRONG about the current cart. The cart can be modified at any time from outside this chat (e.g., via the store scanner or manual clearing). You MUST COMPLETELY IGNORE any cart quantities or item lists mentioned in previous assistant messages. The ONLY correct cart state is the "Current Cart Items" block at the top of this system prompt. Treat any cart listing in the chat history as if it were from a different session entirely.
+
+
+### Guidelines:
+1. **Conversational Responses**: Be extremely friendly, natural, and helpful. Always write your final response as plain, readable text — never as JSON or code blocks.
+2. **Tool Usage**: Use the tool-calling interface to search inventory, add/remove items, or match recipes.
+3. **No Raw Tool Tags**: Do NOT write tool calls as raw text, XML, or `<function>` tags in your response content. Only use the official API tool-calling mechanism.
+4. **No Hallucinations**: Only use the exact SKUs found in the inventory catalog.
+4b. **CRITICAL — DO NOT CLEAR CART BY MISTAKE**: The `clear_cart` tool PERMANENTLY destroys the entire cart. You MUST NEVER call `clear_cart` when the user says "add", "buy", "get", or anything that sounds like they want to put something in the cart. Only call `clear_cart` if the user uses an explicit phrase like: "clear my cart", "empty cart", "wipe the cart", "remove everything", "start over". If in doubt, do NOT call it.
+5. **Displaying Cart and Cart Quantities**:
+   - When asked to show, display, or list the cart, list each item on a new line in a clear, user-friendly bulleted list showing its name and quantity (e.g., "- Product Name: 2"). Do not list the SKU to keep the response clean. Do not call any tools to list the cart; rely strictly on the "Current Cart Items" list provided above.
+   - **CRITICAL**: The "Current Cart Items" block represents the absolute, exact, and up-to-date state of the user's cart. Past chat history requests (e.g., "add 4 items") are already fully processed and reflected in "Current Cart Items". Do NOT sum, add, or accumulate quantities from the chat history with the "Current Cart Items". Do NOT assume the user has items that are not explicitly present in the "Current Cart Items" list.
+5b. **Cart Action Confirmations**: After successfully adding, removing, or clearing items from the cart via a tool call, respond with a short, friendly confirmation message ONLY about what you just did (e.g., "Done! I've added 5 Lays to your cart", "All clear! Your cart is now empty"). **NEVER list the full cart state or say 'Current Cart Items:' after an action** — this creates stale data in the chat history that causes confusion on future requests. Only list cart contents if the user explicitly asks "what's in my cart?" or "show my cart".
+6. **Displaying Search Results / Products**: When listing products from inventory searches or queries:
+   - Always display them as a clean bulleted list on new lines (rather than inline or in paragraphs) for better readability.
+   - Show only the human-friendly product names.
+   - Do NOT display product SKUs (e.g., "QLS-XXXX") in your final response text unless the user specifically asks for the SKU.
+7. **Semantic Relevance Filtering**: The `search_inventory` tool performs a keyword-based search and may return items that merely contain the search term in their name (e.g., searching for "milk" returns "Cadbury Dairy Milk Chocolate" and "Nestle Milkybar White Chocolate", and searching for "onion" returns "Cream and Onion Chips"). When responding to the user, you must intelligently filter these results to only include products that are semantically relevant to the user's actual request. For example, if the user asks for "milk" or raw cooking ingredients, do not list chocolates, chips, or baby foods even if they appeared in the search results.
+8. **General Shopping Suggestions and Chitchat**:
+   - If the user asks for general shopping recommendations, breakfast item suggestions, snacks, greetings, or conversational questions, do NOT call the `generate_and_match_recipe` tool.
+   - Instead, respond conversationally using products that are available in the 'Available Store Catalog' list below (e.g., for breakfast suggest "Nestle Ceregrow Multigrain Cereal", "Standardised Milk", "Organic Eggs", etc.).
+   - Only call the `generate_and_match_recipe` tool when the user is explicitly requesting a recipe or cooking instructions for a specific dish.
+9. **Parallel Tool Calls for Multiple Items**: When the user asks to add, remove, or search for multiple items in a single message (e.g., "add Lays, Snickers, and KitKat"), you MUST issue ALL required tool calls **in a single response as parallel calls** — not one-by-one across multiple turns. This ensures all items are processed reliably.
+10. **NO EMOJIS**: Do NOT use emojis anywhere in your final responses. Keep your language clean, professional, and strictly without any emojis (like 🛒, 🧹, 🍽️, 🥣, etc.).
+
+
+Available Store Catalog (SKUs and Names):
+{catalog_str}
+
+*PRO-TIP FOR CATALOG USAGE*: Since you are provided with the absolute list of all available items in the store in the 'Available Store Catalog' section above, you can and must directly select the matching SKU and call `add_to_cart` or `remove_from_cart` immediately without needing to search the inventory first. Use the `search_inventory` tool ONLY if the item name requested by the user is ambiguous or not clearly matching any of the items in the catalog above.
+"""
+            }
+        ]
+
+        if chat_history:
+            for item in chat_history:
+                role = "user" if item.get("is_user") else "assistant"
+                messages.append({
+                    "role": role,
+                    "content": item.get("text") or ""
+                })
+
+        # Determine model to use (switch to vision-capable model if image is attached)
+        model_to_use = self.model
+        if image_base64:
+            model_to_use = "meta-llama/llama-4-scout-17b-16e-instruct"
+            user_content = [
+                {
+                    "type": "text",
+                    "text": dish_query if dish_query else "What is this image? Tell me if I should add it to my cart or how I can cook with it."
+                },
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": f"data:image/jpeg;base64,{image_base64}"
+                    }
+                }
+            ]
+        else:
+            user_content = dish_query
+            # ── Pre-fetch relevant inventory items and inject into user message ──
+            if dish_query and not image_base64:
+                prefetched = self._prefetch_relevant_items(dish_query)
+                if prefetched:
+                    product_lines = "\n".join(
+                        f"- {it['name']} (SKU: {it['sku']}, Price: ₹{it.get('price_rupees', '?')})"
+                        for it in prefetched
+                    )
+                    user_content = (
+                        f"{dish_query}\n\n"
+                        f"[Context – Matching Store Products]\n"
+                        f"{product_lines}\n"
+                        f"(Use this list to answer directly; only call search_inventory if the user's request is "
+                        f"not covered by these results.)"
+                    )
+
+        # Add the latest user message
+        messages.append({
+            "role": "user",
+            "content": user_content
+        })
+
+        executed_tool_calls = set()
+        for loop_iter in range(6):  # increased from 3: multi-item requests can need up to 6 sequential tool steps
+
+            content = ""
+            tool_calls_dict = {}
+            try:
+                loop = asyncio.get_event_loop()
+                def get_stream(m):
+                    return self.client.chat.completions.create(
+                        model=m,
+                        messages=messages,
+                        tools=tools_definitions,
+                        tool_choice="auto",
+                        max_tokens=1024,
+                        temperature=0.3,
+                        stream=True
+                    )
+                
+                try:
+                    completion_stream = await loop.run_in_executor(None, lambda: get_stream(model_to_use))
+                except Exception as stream_err:
+                    if model_to_use == self.model and self.fallback_model:
+                        print(f"⚠️ [AGENT LLM FALLBACK] Main model {model_to_use} failed: {stream_err}. Falling back to {self.fallback_model}...")
+                        model_to_use = self.fallback_model
+                        completion_stream = await loop.run_in_executor(None, lambda: get_stream(model_to_use))
+                    else:
+                        raise stream_err
+                
+                role = "assistant"
+                for chunk in completion_stream:
+                    delta = chunk.choices[0].delta
+                    if delta.content:
+                        content += delta.content
+                        yield json.dumps({"text_chunk": delta.content}) + "\n"
+                    
+                    if delta.tool_calls:
+                        for tc in delta.tool_calls:
+                            idx = tc.index
+                            if idx not in tool_calls_dict:
+                                tool_calls_dict[idx] = {
+                                    "id": tc.id or "",
+                                    "type": "function",
+                                    "function": {
+                                        "name": tc.function.name or "",
+                                        "arguments": tc.function.arguments or ""
+                                    }
+                                }
+                            else:
+                                if tc.id:
+                                    tool_calls_dict[idx]["id"] += tc.id
+                                if tc.function.name:
+                                    tool_calls_dict[idx]["function"]["name"] += tc.function.name
+                                if tc.function.arguments:
+                                    tool_calls_dict[idx]["function"]["arguments"] += tc.function.arguments
+            except Exception as e:
+                print(f"⚠️ [AGENT LLM FAULT] {e}")
+                if not content:
+                    if mutations:
+                        # Cart was mutated but final reply failed — still report what was done.
+                        details = []
+                        for mut in mutations:
+                            act = mut.get("action")
+                            name = mut.get("name", "items")
+                            qty = mut.get("quantity", 1)
+                            if act == "add":
+                                details.append(f"added {qty} {name}")
+                            elif act == "remove":
+                                details.append(f"removed {qty} {name}")
+                            elif act == "clear":
+                                details.append("cleared your cart")
+                        summary_str = ", ".join(details)
+                        yield json.dumps({"text_chunk": f"Done! I've successfully {summary_str}, but I'm having trouble generating the final reply. Please check your cart to verify."}) + "\n"
+                    else:
+                        # No content, no mutations — backend is unusable for this request.
+                        # Signal 503 so the Flutter client retries the next backend URL.
+                        print(f"⚠️ [AGENT LLM FAULT] No content produced — signalling llm_unavailable to trigger client failover")
+                        yield json.dumps({"llm_unavailable": True}) + "\n"
+                break
+
+            # Reconstruct SimpleNamespace for internal checks
+            tool_calls = []
+            if tool_calls_dict:
+                from types import SimpleNamespace
+                for idx in sorted(tool_calls_dict.keys()):
+                    tc_data = tool_calls_dict[idx]
+                    tool_calls.append(SimpleNamespace(
+                        id=tc_data["id"],
+                        type="function",
+                        function=SimpleNamespace(
+                            name=tc_data["function"]["name"],
+                            arguments=tc_data["function"]["arguments"]
+                        )
+                    ))
+            
+            from types import SimpleNamespace
+            msg = SimpleNamespace(
+                role=role,
+                content=content if content else None,
+                tool_calls=tool_calls if tool_calls else None
+            )
+
+            # Append plain dict to message history list for API compatibility
+            api_msg = {
+                "role": role,
+                "content": content if content else None
+            }
+            if tool_calls_dict:
+                api_msg["tool_calls"] = [
+                    {
+                        "id": tc_data["id"],
+                        "type": "function",
+                        "function": {
+                            "name": tc_data["function"]["name"],
+                            "arguments": tc_data["function"]["arguments"]
+                        }
+                    }
+                    for tc_data in tool_calls_dict.values()
+                ]
+            messages.append(api_msg)
+
+            if not msg.tool_calls:
+                break
+
+            # Check loop prevention first
+            should_break = False
+            for tool_call in msg.tool_calls:
+                call_signature = (tool_call.function.name, tool_call.function.arguments)
+                if call_signature in executed_tool_calls:
+                    print(f"🔁 [LOOP PREVENTED] Agent attempted to call tool '{tool_call.function.name}' with identical arguments {tool_call.function.arguments} again. Breaking loop.")
+                    should_break = True
+                    break
+                executed_tool_calls.add(call_signature)
+
+            if should_break:
+                break
+
+            # Execute tool calls in parallel
+            async def execute_single_tool(tool_call) -> Dict[str, Any]:
+                nonlocal recipe_data
+                tool_name = tool_call.function.name
+                tool_args_str = tool_call.function.arguments
+                arguments = json.loads(tool_args_str)
+                print(f"🛠️ [TOOL CALL] {tool_name} with args {arguments}")
+
+                result_str = ""
+                if tool_name == "search_inventory":
+                    res = await loop.run_in_executor(None, lambda: self.tool_search_inventory(arguments.get("query", "")))
+                    result_str = json.dumps(res)
+                elif tool_name == "add_to_cart":
+                    res = await loop.run_in_executor(None, lambda: self.tool_add_to_cart(user_id, arguments.get("sku"), arguments.get("quantity", 1), mutations))
+                    result_str = res
+                elif tool_name == "remove_from_cart":
+                    res = await loop.run_in_executor(None, lambda: self.tool_remove_from_cart(user_id, arguments.get("sku"), arguments.get("quantity", 1), mutations))
+                    result_str = res
+                elif tool_name == "clear_cart":
+                    res = await loop.run_in_executor(None, lambda: self.tool_clear_cart(user_id, mutations))
+                    result_str = res
+                    # Signal the outer loop to short-circuit with a canned response
+                    return {
+                        "role": "tool",
+                        "tool_call_id": tool_call.id,
+                        "name": tool_name,
+                        "content": result_str,
+                        "__fast_path_response": "Done! Your cart has been cleared. Let me know if you'd like to add anything!"
+                    }
+                elif tool_name == "generate_and_match_recipe":
+                    recipe_data = await self._generate_and_match_recipe_internal(
+                        user_id=user_id,
+                        current_cart_slugs=current_cart_slugs,
+                        dish_query=arguments.get("dish_name"),
+                        servings=arguments.get("servings", servings)
+                    )
+                    result_str = "Successfully generated recipe."
+                elif tool_name == "get_nutrition_info":
+                    item_query = arguments.get("item_query", "")
+                    res = await self.nutrition_service.get_nutrition(item_query)
+                    if res:
+                        result_str = json.dumps({
+                            "matched_item": item_query,
+                            "nutrients_per_100g": {
+                                "calories": f"{res.get('calories')} kcal",
+                                "protein": f"{res.get('protein')}g",
+                                "carbohydrates": f"{res.get('carbs')}g",
+                                "fats": f"{res.get('fat')}g"
+                            }
+                        })
+                    else:
+                        result_str = f"Sorry, could not find nutritional values for '{item_query}'."
+                else:
+                    result_str = f"Error: Tool '{tool_name}' not found."
+
+                return {
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "name": tool_name,
+                    "content": result_str
+                }
+
+            tasks = [execute_single_tool(tc) for tc in msg.tool_calls]
+            responses = await asyncio.gather(*tasks)
+
+            # Check if any tool requested a fast-path early exit
+            fast_path_msg = None
+            for resp in responses:
+                if resp and resp.get("__fast_path_response"):
+                    fast_path_msg = resp.pop("__fast_path_response")
+                    break
+
+            messages.extend(responses)
+
+            if fast_path_msg:
+                yield json.dumps({"text_chunk": fast_path_msg}) + "\n"
+                break
+
+            if should_break:
+                break
+
+        # Yield final metadata chunk
+        yield json.dumps({
+            "cart_mutations": mutations if mutations else None,
+            "recipe": recipe_data if recipe_data else None
+        }) + "\n"

app/agents/tools/__init__.py

@@ -0,0 +1 @@
+# Agent tools package initialization

app/agents/tools/quantity_parser_tool.py

@@ -0,0 +1,206 @@
+import re
+from typing import Dict, Any, Optional
+
+# Words that describe preparation, not the ingredient itself — stripped from name
+_PREP_WORDS = re.compile(
+    r"^(chopped|minced|diced|grated|sliced|crushed|ground|peeled|toasted|roasted|"
+    r"fresh|freshly|frozen|canned|organic|whole|small|large|medium|"
+    r"optional|divided|cloves?|"
+    r"cups?|tablespoons?|tbsp|teaspoons?|tsp|grams?|g|kg|ml|liters?|l|"
+    r"pinch|sprinkle|dash|drop|inch(?:es)?|pieces?|sticks?|slices?)\s+",
+    re.IGNORECASE
+)
+
+# Unit words that can follow conversational quantities ("to taste", "for garnish")
+_CONVERSATIONAL_UNITS = {"pinch", "dash", "drop", "sprinkle"}
+
+class QuantityParserTool:
+    """Tool to parse ingredients and extract quantity information"""
+
+    @staticmethod
+    def get_tool_definition() -> Dict[str, Any]:
+        """Returns the tool definition for Groq function calling"""
+        return {
+            "type": "function",
+            "function": {
+                "name": "parse_ingredient_quantity",
+                "description": "Parse an ingredient string to extract quantity, unit, and ingredient name. Handles various formats like '1 cup flour', '2 tbsp butter', '3 eggs', etc.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "ingredient_string": {
+                            "type": "string",
+                            "description": "The ingredient string to parse (e.g., '2 cups flour', '1 tablespoon olive oil')"
+                        }
+                    },
+                    "required": ["ingredient_string"]
+                }
+            }
+        }
+
+    @staticmethod
+    def _strip_prep_words(name: str) -> str:
+        """Remove leading preparation descriptors (chopped, fresh, etc.) from name"""
+        while True:
+            cleaned = _PREP_WORDS.sub("", name).strip()
+            if cleaned == name:
+                break
+            name = cleaned
+        return name.strip("-, ")
+
+    @staticmethod
+    def _handle_conversational_phrases(ingredient: str, raw_input: str) -> Optional[Dict[str, Any]]:
+        """Handle non-numeric conversational phrases like 'to taste', 'for garnish', 'pinch of'"""
+        ingredient_lower = ingredient.lower()
+
+        # "to taste" — can appear at start or end ("to taste Pepper" / "Salt to taste")
+        if "to taste" in ingredient_lower:
+            name = re.sub(r"\bto taste\b", "", ingredient, flags=re.IGNORECASE).strip("-, ")
+            unit, name = QuantityParserTool._extract_conversational_unit(name)
+            return {
+                "quantity": "to taste",
+                "unit": unit,
+                "name": QuantityParserTool._strip_prep_words(name),
+                "raw_input": raw_input
+            }
+
+        # "as needed" — "as needed Spices", "as needed Salt"
+        if "as needed" in ingredient_lower[:20]:
+            name = re.sub(r"\bas needed\b", "", ingredient, flags=re.IGNORECASE).strip("-, ")
+            unit, name = QuantityParserTool._extract_conversational_unit(name)
+            return {
+                "quantity": "as needed",
+                "unit": unit,
+                "name": QuantityParserTool._strip_prep_words(name),
+                "raw_input": raw_input
+            }
+
+        # "for garnish" → "Fresh Cilantro for garnish"
+        if "for garnish" in ingredient_lower:
+            name = re.sub(r"\bfor garnish\b", "", ingredient, flags=re.IGNORECASE).strip("-, ")
+            unit, name = QuantityParserTool._extract_conversational_unit(name)
+            return {
+                "quantity": "for garnish",
+                "unit": unit,
+                "name": QuantityParserTool._strip_prep_words(name),
+                "raw_input": raw_input
+            }
+
+        # "a pinch of ..." / "pinch of ..." / "1 pinch of ..." / "2 pinches of ..."
+        pinch_match = re.match(r"^(\d+\.?\d*)?\s*(a\s+)?pinch(?:es)?\s+of\s+(.+)", ingredient, re.IGNORECASE)
+        if pinch_match:
+            quantity = pinch_match.group(1) or "1"
+            name = pinch_match.group(3).strip()
+            return {
+                "quantity": quantity.strip(),
+                "unit": "pinch",
+                "name": QuantityParserTool._strip_prep_words(name),
+                "raw_input": raw_input
+            }
+
+        return None
+
+    @staticmethod
+    def _extract_conversational_unit(text: str) -> tuple:
+        """After stripping a conversational phrase, check if the remainder starts
+        with a known unit word (e.g. 'pinch', 'dash') and extract it."""
+        text = text.strip()
+        for word in sorted(_CONVERSATIONAL_UNITS, key=len, reverse=True):
+            if text.lower().startswith(word) and (len(text) == len(word) or not text[len(word)].isalpha()):
+                return word, text[len(word):].strip("-, ")
+        return "", text
+
+    @staticmethod
+    def _post_process(result: Dict[str, Any]) -> Dict[str, Any]:
+        """Clean up residual noise: trailing dashes on quantities and duplicate word leaks in names."""
+        # Clean trailing dashes from quantity strings (e.g. "1-" → "1")
+        qty = result.get("quantity", "")
+        if qty.endswith("-"):
+            qty = qty.rstrip("-").strip()
+        result["quantity"] = qty
+
+        # De-duplicate name words where one is a case-insensitive substring of another
+        # e.g. "onion Onions" → "Onions", "Salt salt" → "Salt"
+        name = result.get("name", "")
+        words = name.split()
+        if len(words) >= 2:
+            cleaned = []
+            for w in words:
+                wl = w.lower()
+                dup = False
+                for j, (existing, existing_lower) in enumerate(cleaned):
+                    if wl == existing_lower or wl in existing_lower or existing_lower in wl:
+                        if len(w) >= len(existing):
+                            cleaned[j] = (w, wl)
+                        dup = True
+                        break
+                if not dup:
+                    cleaned.append((w, wl))
+            name = " ".join(c[0] for c in cleaned)
+            result["name"] = name
+
+        return result
+
+    @staticmethod
+    def execute(ingredient_string: str) -> Dict[str, Any]:
+        """Parse an ingredient string and extract components"""
+        ingredient = ingredient_string.strip()
+        
+        # Remove leading symbols (▢, •, -, +)
+        ingredient = re.sub(r"^[\s▢•\-+]*", "", ingredient).strip()
+        
+        # Remove numbered list markers (e.g., "3. ")
+        ingredient = re.sub(r"^\d+\.\s*", "", ingredient).strip()
+        
+        # Handle conversational phrases before regex parsing
+        conv_result = QuantityParserTool._handle_conversational_phrases(ingredient, ingredient_string)
+        if conv_result:
+            return QuantityParserTool._post_process(conv_result)
+        
+        # Match ANY numeric quantity, unicode fraction, or fraction expression at the start
+        num_match = re.match(r"^([\d½¼¾⅓⅔⅛\/\.\-\s]+)", ingredient)
+        
+        if num_match and num_match.group(1).strip():
+            quantity_num = num_match.group(1).strip()
+            remainder = ingredient[num_match.end():].strip()
+            
+            # Check if the remainder starts with a recognized unit
+            unit_pattern = r"^(cups?|tablespoons?|tbsp|teaspoons?|tsp|grams?|g|kg|ml|liters?|l)\b"
+            unit_match = re.match(unit_pattern, remainder, re.IGNORECASE)
+            
+            if unit_match:
+                unit = unit_match.group(1)
+                name = remainder[unit_match.end():].strip()
+                quantity = f"{quantity_num} {unit}"
+            else:
+                # No standard unit matched
+                quantity = quantity_num
+                name = remainder
+                
+            # Clean up content in parentheses from the name
+            name = re.sub(r"\([^)]*\)", "", name).strip()
+            
+            return QuantityParserTool._post_process({
+                "quantity": quantity,
+                "unit": unit_match.group(1) if unit_match else "",
+                "name": QuantityParserTool._strip_prep_words(name),
+                "raw_input": ingredient_string
+            })
+        
+        # Fallback: Check if it starts with a single digit or fraction symbol
+        fallback_match = re.match(r"^([0-9½¼¾⅓⅔⅛])\s*(.*)$", ingredient)
+        if fallback_match:
+            return QuantityParserTool._post_process({
+                "quantity": fallback_match.group(1),
+                "unit": "",
+                "name": QuantityParserTool._strip_prep_words(fallback_match.group(2).strip()),
+                "raw_input": ingredient_string
+            })
+        
+        # No quantity found, assume ingredient name only
+        return QuantityParserTool._post_process({
+            "quantity": "",
+            "unit": "",
+            "name": QuantityParserTool._strip_prep_words(ingredient),
+            "raw_input": ingredient_string
+        })

app/config.py

@@ -0,0 +1,25 @@
+import os
+
+# Model settings
+MODEL_ID = "Xenova/clip-vit-base-patch32"
+PROCESSOR_ID = "openai/clip-vit-base-patch32"
+DEVICE = "cpu"
+
+# ONNX options
+INTRA_OP_NUM_THREADS = 4
+INTER_OP_NUM_THREADS = 4
+
+# Storage paths
+IMAGES_DIR = "captured_images"
+
+# Vector Search
+SIMILARITY_THRESHOLD = 0.65
+
+# Object Detection (YOLOv8n ONNX)
+ENABLE_OBJECT_DETECTION = os.getenv("ENABLE_OBJECT_DETECTION", "false").lower() == "true"
+YOLO_MODEL_ID = os.getenv("YOLO_MODEL_ID", "ultralytics/yolov8n")
+YOLO_MODEL_FILENAME = os.getenv("YOLO_MODEL_FILENAME", "yolov8n.onnx")
+DETECTION_CONFIDENCE_THRESHOLD = float(os.getenv("DETECTION_CONFIDENCE_THRESHOLD", "0.25"))
+DETECTION_IOU_THRESHOLD = float(os.getenv("DETECTION_IOU_THRESHOLD", "0.45"))
+MAX_DETECTIONS = int(os.getenv("MAX_DETECTIONS", "3"))
+CROP_PADDING_RATIO = float(os.getenv("CROP_PADDING_RATIO", "0.10"))

app/main.py

@@ -0,0 +1,43 @@
+import os
+from dotenv import load_dotenv
+
+# Explicitly load .env file from the hf_server directory
+base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+dotenv_path = os.path.join(base_dir, ".env")
+load_dotenv(dotenv_path=dotenv_path, override=True)
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from .routes import health, detection, chat, cart_analysis
+from .services.http_client import init_http_client, close_http_client
+
+app = FastAPI()
+
+# Enable CORS so Flutter Web or local clients can call it directly
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:50220",
+        "http://127.0.0.1:50220",
+        "http://localhost:8000",
+        "http://127.0.0.1:8000",
+    ],
+    allow_origin_regex=r"https?://(localhost|127\.0\.0\.1)(:\d+)?",
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(health.router)
+app.include_router(detection.router)
+app.include_router(chat.router)
+app.include_router(cart_analysis.router)
+
+@app.on_event("startup")
+async def startup_event():
+    await init_http_client()
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    await close_http_client()

app/models/__init__.py

@@ -0,0 +1,3 @@
+from .chat import ChatRequest
+
+__all__ = ["ChatRequest"]

app/models/chat.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+from typing import List, Optional
+
+class RecipeStructure(BaseModel):
+    dish: str
+    servings: int
+    ingredients: List[str]
+    instructions: List[str]
+
+class ChatMessagePayload(BaseModel):
+    is_user: bool
+    text: str
+
+class CartItemPayload(BaseModel):
+    sku: str
+    name: str
+    quantity: int
+
+class ChatRequest(BaseModel):
+    user_id: str
+    current_cart_slugs: List[str]
+    dish_query: str
+    servings: int
+    chat_history: Optional[List[ChatMessagePayload]] = None
+    current_cart: Optional[List[CartItemPayload]] = None
+    image_base64: Optional[str] = None

app/routes/__init__.py

@@ -0,0 +1 @@
+# Routes package initialization

app/routes/cart_analysis.py

@@ -0,0 +1,44 @@
+from typing import List, Optional, Any, Dict
+from pydantic import BaseModel
+from fastapi import APIRouter, HTTPException
+import traceback
+
+from app.agents.missing_regulars_agent import MissingRegularsAgent
+
+router = APIRouter(prefix="/cart-analysis", tags=["Cart Analysis"])
+agent = MissingRegularsAgent()
+
+class CartItem(BaseModel):
+    id: str = None
+    sku: str = None
+    name: str = None
+    price: float = 0.0
+    quantity: int = 1
+    
+    def dict(self, **kwargs):
+        return super().model_dump(**kwargs)
+
+class CartAnalysisRequest(BaseModel):
+    user_id: str
+    current_cart: List[CartItem] = []
+
+@router.post("/missing-regulars")
+async def get_missing_regulars(payload: CartAnalysisRequest):
+    """
+    Analyzes the user's past 90 days of order history to identify items 
+    they buy regularly but haven't added to their current cart.
+    Returns a friendly LLM-generated message and a list of structured item suggestions.
+    """
+    try:
+        user = str(payload.user_id).lower().strip()
+        # Convert pydantic models to dicts for the agent
+        current_cart = [item.dict() for item in payload.current_cart]
+
+        result = await agent.analyze_cart(user_id=user, current_cart=current_cart)
+        return result
+        
+    except Exception as e:
+        print("\n=== CRITICAL API ROUTE ERROR TRACEBACK ===")
+        traceback.print_exc()
+        print("==========================================\n")
+        raise HTTPException(status_code=500, detail=str(e))

app/routes/chat.py

@@ -0,0 +1,109 @@
+import traceback
+import json
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+from app.models.chat import ChatRequest
+from app.agents.shopping_assistant_agent import ShoppingAssistantAgent
+from app.utils.cart_state import live_cart_memory
+
+router = APIRouter(prefix="/chat", tags=["Chat Management"])
+agent = ShoppingAssistantAgent()
+
+@router.post("/message")
+async def send_chat_message(payload: ChatRequest):
+    """
+    Non-streaming endpoint for backward compatibility (e.g. cart sync, tests).
+    Accumulates the generator chunks and returns a flat JSON dictionary.
+    """
+    try:
+        user = str(payload.user_id).lower().strip()
+        slugs = [str(s) for s in payload.current_cart_slugs]
+        query = str(payload.dish_query)
+        srv = int(payload.servings)
+        
+        history = []
+        if payload.chat_history:
+            history = [{"is_user": h.is_user, "text": h.text} for h in payload.chat_history]
+
+        current_cart = []
+        if payload.current_cart:
+            current_cart = [{"sku": c.sku, "name": c.name, "quantity": c.quantity} for c in payload.current_cart]
+
+        # ── Source-of-truth sync ────────────────────────────────────────────────
+        # Flutter's CartService is the authoritative cart state. Any external
+        # modifications (dashboard scanner, checkout, manual cart clear) are
+        # reflected here by resetting the server-side memory to match before
+        # running any tool calls.
+        live_cart_memory.sync_from_client(user, current_cart)
+
+        result = await agent.process_recipe_workflow(
+            user_id=user,
+            current_cart_slugs=slugs,
+            dish_query=query,
+            servings=srv,
+            chat_history=history,
+            current_cart=current_cart,
+            image_base64=payload.image_base64
+        )
+
+        if result.get("llm_unavailable"):
+            raise HTTPException(
+                status_code=503,
+                detail="LLM rate limit exceeded. Please try again later."
+            )
+
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        print("\n=== CRITICAL API ROUTE ERROR TRACEBACK ===")
+        traceback.print_exc()
+        print("==========================================\n")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/cart/{user_id}")
+async def get_user_live_cart(user_id: str):
+    """
+    Endpoint for Flutter client to fetch the active item quantities 
+    that the AI agent added via tool calls.
+    """
+    raw_cart_data = live_cart_memory.get_cart(user_id.lower().strip())
+    
+    formatted_items = [
+        {"sku": sku, "quantity": qty}
+        for sku, qty in raw_cart_data.items()
+    ]
+    
+    return {
+        "user_id": user_id,
+        "items": formatted_items
+    }
+
+
+@router.post("/test-notification")
+async def trigger_test_notification():
+    """
+    Simulates a payment notification generation from the backend.
+    """
+    import random
+    success = random.choice([True, False])
+    txn_id = f"pay_{''.join(random.choices('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', k=12))}" if success else ""
+    amount = random.choice([250.00, 499.00, 999.00, 1499.00, 2999.00])
+    
+    if success:
+        message = f"Payment of INR {amount:,.2f} to Qless Merchant was successful."
+    else:
+        reason = random.choice([
+            "declined by the issuing bank",
+            "insufficient funds in the account",
+            "incorrect OTP entered",
+            "network timeout during processing"
+        ])
+        message = f"Payment of INR {amount:,.2f} failed: {reason}."
+        
+    return {
+        "success": success,
+        "message": message,
+        "transactionId": txn_id
+    }

app/routes/detection.py

@@ -0,0 +1,388 @@
+import os
+import io
+import time
+import datetime
+from fastapi import APIRouter, File, UploadFile, Header
+from fastapi.responses import FileResponse, HTMLResponse
+from PIL import Image
+import numpy as np
+
+from ..config import (
+    IMAGES_DIR,
+    SIMILARITY_THRESHOLD,
+    ENABLE_OBJECT_DETECTION,
+    DETECTION_CONFIDENCE_THRESHOLD,
+    DETECTION_IOU_THRESHOLD,
+    MAX_DETECTIONS,
+    CROP_PADDING_RATIO,
+)
+from ..services.detector import processor, session, get_image_embedding
+from ..services.chroma import ChromaSearcher
+from ..services.supabase import SupabaseQuerier
+
+if ENABLE_OBJECT_DETECTION:
+    from ..services.object_detector import detect_objects, crop_objects
+
+router = APIRouter(tags=["Product Detection"])
+
+@router.post("/embed")
+async def get_embedding(file: UploadFile = File(...)):
+    """Generate and return raw CLIP embeddings for the uploaded product image."""
+    try:
+        contents = await file.read()
+        embedding = get_image_embedding(contents)
+        return {"status": "success", "embedding": embedding}
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+@router.post("/detect")
+async def detect_item(
+    file: UploadFile = File(...),
+    x_chroma_token: str = Header(default=None),
+    x_supabase_url: str = Header(default=None),
+    x_supabase_key: str = Header(default=None)
+):
+    """
+    Perform full end-to-end product detection:
+    When ENABLE_OBJECT_DETECTION=true:
+      1. Run YOLO object detection to find bounding boxes.
+      2. Crop each detected object region.
+      3. Generate CLIP embeddings per crop.
+      4. Search ChromaDB for the best match across all crops.
+    Otherwise (legacy path):
+      1. Preprocess uploaded image and generate CLIP vector embeddings.
+      2. Search the vector catalog in ChromaDB for similarity matches.
+      3. Retrieve the matching item metadata from local catalog or Supabase DB.
+    """
+    start_total = time.time()
+    try:
+        t0 = time.time()
+        contents = await file.read()
+        t_read = time.time() - t0
+
+        # -----------------------------------------------------------------
+        # Object-detection path: YOLO crop -> per-crop CLIP -> best match
+        # -----------------------------------------------------------------
+        if ENABLE_OBJECT_DETECTION:
+            t0 = time.time()
+            detections = detect_objects(
+                contents,
+                conf_threshold=DETECTION_CONFIDENCE_THRESHOLD,
+                iou_threshold=DETECTION_IOU_THRESHOLD,
+                max_detections=MAX_DETECTIONS,
+            )
+            t_detect = time.time() - t0
+
+            if not detections:
+                print(
+                    f"[detect-obj] No objects detected (detect={t_detect:.4f}s, "
+                    f"total={time.time() - start_total:.4f}s)"
+                )
+                return {
+                    "status": "success",
+                    "match_found": False,
+                    "reason": "No objects detected in image",
+                }
+
+            t0 = time.time()
+            crops = crop_objects(contents, detections, padding_ratio=CROP_PADDING_RATIO)
+            t_crop = time.time() - t0
+
+            best_slug = None
+            best_distance = float("inf")
+            t_clip_total = 0.0
+
+            for i, crop_bytes in enumerate(crops):
+                t0 = time.time()
+                embedding = get_image_embedding(crop_bytes)
+                t_clip = time.time() - t0
+                t_clip_total += t_clip
+
+                searcher = ChromaSearcher(token=x_chroma_token)
+                search_result = await searcher.search(embedding)
+                if search_result is None:
+                    continue
+
+                slug, distance = search_result
+                if distance <= SIMILARITY_THRESHOLD and distance < best_distance:
+                    best_slug = slug
+                    best_distance = distance
+
+            if best_slug is None:
+                print(
+                    f"[detect-obj] No match found across {len(crops)} crops "
+                    f"(detect={t_detect:.4f}s, crop={t_crop:.4f}s, "
+                    f"clip={t_clip_total:.4f}s, total={time.time() - start_total:.4f}s)"
+                )
+                return {
+                    "status": "success",
+                    "match_found": False,
+                    "reason": f"No match across {len(crops)} detected crops",
+                }
+
+            slug = best_slug
+
+            if x_supabase_url and x_supabase_key:
+                t0 = time.time()
+                querier = SupabaseQuerier(url=x_supabase_url, key=x_supabase_key)
+                product_data = await querier.get_product_by_slug(slug)
+                t_supabase = time.time() - t0
+            else:
+                product_data = None
+                t_supabase = 0.0
+
+            print(
+                f"[detect-obj] Profiling: Read={t_read:.4f}s, Detect={t_detect:.4f}s, "
+                f"Crop={t_crop:.4f}s, CLIP={t_clip_total:.4f}s, "
+                f"Supabase={t_supabase:.4f}s. "
+                f"Total={time.time() - start_total:.4f}s"
+            )
+
+            if product_data:
+                return {
+                    "status": "success",
+                    "match_found": True,
+                    "item": {
+                        "sku": product_data.get("sku"),
+                        "slug": product_data.get("slug"),
+                        "name": product_data.get("name"),
+                        "price_rupees": float(product_data.get("price_rupees", 0.0)),
+                    },
+                }
+            else:
+                name_fallback = slug.replace("-", " ").upper()
+                return {
+                    "status": "success",
+                    "match_found": True,
+                    "item": {
+                        "sku": "UNLISTED",
+                        "slug": slug,
+                        "name": name_fallback,
+                        "price_rupees": 0.0,
+                    },
+                }
+
+        # -----------------------------------------------------------------
+        # Legacy whole-image CLIP path
+        # -----------------------------------------------------------------
+        t0 = time.time()
+        image = Image.open(io.BytesIO(contents)).convert("RGB")
+        image = image.resize((224, 224), Image.Resampling.BILINEAR)
+        inputs = processor(images=image, return_tensors="np")
+        pixel_values = inputs["pixel_values"]
+        t_preprocess = time.time() - t0
+
+        t0 = time.time()
+        outputs = session.run(["image_embeds"], {"pixel_values": pixel_values})
+        image_embeds = outputs[0]
+        t_onnx = time.time() - t0
+
+        norm = np.linalg.norm(image_embeds, axis=-1, keepdims=True)
+        normalized_image_embeds = image_embeds / (norm + 1e-12)
+        embedding = normalized_image_embeds[0].tolist()
+
+        t0 = time.time()
+        searcher = ChromaSearcher(token=x_chroma_token)
+        search_result = await searcher.search(embedding)
+        t_chroma = time.time() - t0
+
+        if search_result is None:
+            print(f"[detect] Finished (No ChromaDB Response) in {time.time() - start_total:.4f}s")
+            return {"status": "success", "match_found": False, "reason": "No ChromaDB response"}
+
+        slug, distance = search_result
+        if distance > SIMILARITY_THRESHOLD:
+            print(f"[detect] Distance {distance} exceeds threshold {SIMILARITY_THRESHOLD} for {slug} (Finished in {time.time() - start_total:.4f}s)")
+            return {"status": "success", "match_found": False, "reason": f"Distance {distance} exceeds threshold {SIMILARITY_THRESHOLD}"}
+
+        # Only query Supabase if the client requested it by sending credentials.
+        # Otherwise, skip to bypass database query latency and rely on client-side local lookup.
+        if x_supabase_url and x_supabase_key:
+            t0 = time.time()
+            querier = SupabaseQuerier(url=x_supabase_url, key=x_supabase_key)
+            product_data = await querier.get_product_by_slug(slug)
+            t_supabase = time.time() - t0
+        else:
+            product_data = None
+            t_supabase = 0.0
+
+        print(f"[detect] Profiling: Read={t_read:.4f}s, Preprocess={t_preprocess:.4f}s, ONNX={t_onnx:.4f}s, Chroma={t_chroma:.4f}s, Supabase={t_supabase:.4f}s. Total={time.time() - start_total:.4f}s")
+
+        if product_data:
+            return {
+                "status": "success",
+                "match_found": True,
+                "item": {
+                    "sku": product_data.get("sku"),
+                    "slug": product_data.get("slug"),
+                    "name": product_data.get("name"),
+                    "price_rupees": float(product_data.get("price_rupees", 0.0))
+                }
+            }
+        else:
+            name_fallback = slug.replace('-', ' ').upper()
+            return {
+                "status": "success",
+                "match_found": True,
+                "item": {
+                    "sku": "UNLISTED",
+                    "slug": slug,
+                    "name": name_fallback,
+                    "price_rupees": 0.0
+                }
+            }
+    except Exception as e:
+        print(f"[detect] Exception: {e}")
+        return {"status": "error", "message": str(e)}
+
+@router.get("/captured_images/{filename}")
+async def get_captured_image(filename: str):
+    """Fetch a previously captured scan image from local disk storage."""
+    filepath = os.path.join(IMAGES_DIR, filename)
+    if os.path.exists(filepath):
+        return FileResponse(filepath)
+    return {"error": "File not found"}
+
+@router.get("/gallery", response_class=HTMLResponse)
+async def get_gallery():
+    """Render a Scandinavian-modern product gallery page showcasing scanned items history."""
+    files = []
+    if os.path.exists(IMAGES_DIR):
+        for f in os.listdir(IMAGES_DIR):
+            if f.lower().endswith(('.jpg', '.jpeg', '.png')):
+                fp = os.path.join(IMAGES_DIR, f)
+                mtime = os.path.getmtime(fp)
+                files.append((f, mtime))
+    
+    files.sort(key=lambda x: x[1], reverse=True)
+    
+    # Render Scandinavian modern light themed gallery page
+    html_content = """<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Scanned Products Gallery | QLESS</title>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        body {
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            background-color: #F4F7F8;
+            color: #2D3748;
+            margin: 0;
+            padding: 40px 24px;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+        }
+        .container {
+            width: 100%;
+            max-width: 1100px;
+        }
+        header {
+            margin-bottom: 40px;
+            text-align: center;
+        }
+        h1 {
+            font-size: 2.25rem;
+            font-weight: 700;
+            color: #1A202C;
+            margin: 0 0 8px 0;
+            letter-spacing: -0.025em;
+        }
+        p {
+            color: #718096;
+            font-size: 1.1rem;
+            margin: 0;
+        }
+        .grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+            gap: 24px;
+            margin-top: 20px;
+        }
+        .card {
+            background: #FFFFFF;
+            border-radius: 18px;
+            overflow: hidden;
+            box-shadow: 0 4px 20px rgba(0, 0, 0, 0.03);
+            border: 1px solid rgba(0, 0, 0, 0.04);
+            transition: transform 0.25s cubic-bezier(0.4, 0, 0.2, 1), box-shadow 0.25s cubic-bezier(0.4, 0, 0.2, 1);
+        }
+        .card:hover {
+            transform: translateY(-4px);
+            box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06);
+        }
+        .card-img-wrapper {
+            position: relative;
+            width: 100%;
+            padding-top: 100%; /* 1:1 Aspect Ratio */
+            background-color: #EDF2F7;
+        }
+        .card img {
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            object-fit: cover;
+        }
+        .info {
+            padding: 16px;
+            font-size: 0.85rem;
+            color: #718096;
+            font-weight: 500;
+            text-align: center;
+            background: #FAFCFC;
+            border-top: 1px solid #E2E8F0;
+        }
+        .empty-state {
+            grid-column: 1 / -1;
+            text-align: center;
+            padding: 80px 20px;
+            background: #FFFFFF;
+            border-radius: 18px;
+            border: 1px dashed #E2E8F0;
+            color: #A0AEC0;
+            font-size: 1.1rem;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <header>
+            <h1>Product Scan History</h1>
+            <p>A history of all product images captured by the AI Shopping Assistant.</p>
+        </header>
+        <div class="grid">
+    """
+    
+    for f, mtime in files:
+        dt = datetime.datetime.fromtimestamp(mtime).strftime('%Y-%m-%d %H:%M:%S')
+        html_content += f"""
+            <div class="card">
+                <a href="/captured_images/{f}" target="_blank">
+                    <div class="card-img-wrapper">
+                        <img src="/captured_images/{f}" alt="Scan from {dt}">
+                    </div>
+                </a>
+                <div class="info">{dt}</div>
+            </div>
+        """
+        
+    if not files:
+        html_content += """
+            <div class="empty-state">
+                No scanned images found yet. Start scanning from the app!
+            </div>
+        """
+        
+    html_content += """
+        </div>
+    </div>
+</body>
+</html>
+    """
+    return html_content
+
+

app/routes/health.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter
+from ..config import MODEL_ID, DEVICE
+
+router = APIRouter(tags=["Health & Status"])
+
+@router.api_route("/health", methods=["GET", "HEAD"])
+def health_check():
+    """Liveness probe to verify the server is running and accessible."""
+    return {"status": "ok"}
+
+@router.get("/")
+def read_root():
+    """Retrieve basic server status metadata and active model details."""
+    return {
+        "status": "running", 
+        "model": MODEL_ID,
+        "device": DEVICE
+    }

app/services/__init__.py

@@ -0,0 +1 @@
+# Services package initialization

app/services/chroma.py

@@ -0,0 +1,62 @@
+import os
+import re
+import httpx
+from .http_client import http_client
+
+SLUG_STRIP_PATTERN = re.compile(r'-\d+$')
+
+class ChromaSearcher:
+    def __init__(self, token: str = None):
+        self.api_key = token or os.environ.get("CHROMA_API_KEY", "")
+        self.tenant = "99526d4b-48cf-4b20-896b-0947aa36d4ab"
+        self.database = "QLESS"
+        self.collection_id = "c1102322-920e-4775-96c1-e324bdadaa1d"
+        self.url = f"https://api.trychroma.com/api/v2/tenants/{self.tenant}/databases/{self.database}/collections/{self.collection_id}/query"
+
+    async def search(self, embedding: list[float]) -> tuple[str, float] | None:
+        if not self.api_key:
+            print("[ChromaSearcher] Warning: No Chroma API key found.")
+            return None
+
+        headers = {
+            "x-chroma-token": self.api_key,
+            "Content-Type": "application/json"
+        }
+        payload = {
+            "query_embeddings": [embedding],
+            "n_results": 1
+        }
+
+        client = http_client if http_client is not None else httpx.AsyncClient()
+        close_client = http_client is None
+        try:
+            response = await client.post(self.url, headers=headers, json=payload, timeout=5.0)
+            if response.status_code == 200:
+                data = response.json()
+                metadatas = data.get("metadatas", [])
+                distances = data.get("distances", [])
+ 
+                if metadatas and metadatas[0] and metadatas[0][0]:
+                    item_meta = metadatas[0][0]
+                    raw_name = item_meta.get("product_name", "Unknown Item")
+                    slug = self._normalize_slug(str(raw_name))
+                    distance = distances[0][0] if (distances and distances[0]) else 2.0
+                    return slug, float(distance)
+            else:
+                status = response.status_code
+                print(f"[ChromaSearcher] Query failed: {status} - {response.text}")
+        except Exception as e:
+            print(f"[ChromaSearcher] Error querying ChromaDB: {e}")
+        finally:
+            if close_client:
+                await client.aclose()
+        return None
+
+    def _normalize_slug(self, slug: str) -> str:
+        clean_slug = SLUG_STRIP_PATTERN.sub('', slug)
+        mapping = {
+            'roasted-almond-chocolate-bar-cadbury': 'dairy-milk-roast-almond-cadbury',
+            'cadbury-dairy-milk-crispello': 'dairy-milk-crispello-cadbury',
+            'fruit-and-nut-milk-chocolate-bar-cadbury': 'dairy-milk-chocolate-cadbury',
+        }
+        return mapping.get(clean_slug, clean_slug)

app/services/detector.py

@@ -0,0 +1,35 @@
+import io
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+from huggingface_hub import hf_hub_download
+from transformers import CLIPProcessor
+from ..config import MODEL_ID, PROCESSOR_ID, INTRA_OP_NUM_THREADS, INTER_OP_NUM_THREADS, DEVICE
+
+print(f"Loading CLIP processor '{PROCESSOR_ID}'...")
+processor = CLIPProcessor.from_pretrained(PROCESSOR_ID)
+
+print(f"Downloading ONNX model '{MODEL_ID}'...")
+model_file = hf_hub_download(repo_id=MODEL_ID, filename="onnx/vision_model.onnx")
+
+print("Initializing ONNX Runtime session...")
+# Limit intra-op and inter-op threads to match environment core count (typically 2 on free space CPU)
+ort_options = ort.SessionOptions()
+ort_options.intra_op_num_threads = INTRA_OP_NUM_THREADS
+ort_options.inter_op_num_threads = INTER_OP_NUM_THREADS
+session = ort.InferenceSession(model_file, sess_options=ort_options, providers=["CPUExecutionProvider"])
+print("Model loaded successfully!")
+
+def get_image_embedding(contents: bytes) -> list[float]:
+    image = Image.open(io.BytesIO(contents)).convert("RGB")
+    image = image.resize((224, 224), Image.Resampling.BILINEAR)
+    inputs = processor(images=image, return_tensors="np")
+    pixel_values = inputs["pixel_values"]
+    
+    outputs = session.run(["image_embeds"], {"pixel_values": pixel_values})
+    image_embeds = outputs[0]
+    
+    norm = np.linalg.norm(image_embeds, axis=-1, keepdims=True)
+    normalized_image_embeds = image_embeds / (norm + 1e-12)
+    
+    return normalized_image_embeds[0].tolist()

app/services/http_client.py

@@ -0,0 +1,13 @@
+import httpx
+
+http_client: httpx.AsyncClient | None = None
+
+async def init_http_client():
+    global http_client
+    http_client = httpx.AsyncClient()
+
+async def close_http_client():
+    global http_client
+    if http_client:
+        await http_client.aclose()
+        http_client = None

app/services/nutrition_service.py

@@ -0,0 +1,177 @@
+import os
+import httpx
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class NutritionService:
+    def __init__(self):
+        self.api_key = os.getenv("USDA_API_KEY")
+        self.base_url = "https://api.nal.usda.gov/fdc/v1/foods/search"
+
+    def _score_food(self, food: dict, query: str) -> float:
+        from difflib import SequenceMatcher
+        desc = food.get("description", "").lower()
+        q_low = query.lower()
+        
+        score = SequenceMatcher(None, q_low, desc).ratio()
+        
+        q_tokens = [w.strip(",.()\"'").rstrip("s") for w in q_low.split() if w.strip()]
+        d_tokens = [w.strip(",.()\"'").rstrip("s") for w in desc.lower().split() if w.strip()]
+        
+        if not q_tokens or not d_tokens:
+            return score
+            
+        core_noun = q_tokens[-1]
+        adjectives = set(q_tokens[:-1])
+        
+        if core_noun in d_tokens:
+            score += 3.0
+        else:
+            has_adjective_match = False
+            for adj in adjectives:
+                if adj in d_tokens:
+                    has_adjective_match = True
+            if has_adjective_match:
+                score -= 4.0
+
+        for idx, token in enumerate(q_tokens):
+            if token in d_tokens:
+                weight = (idx + 1) / len(q_tokens)
+                score += weight * 1.5
+
+        d_first = desc.split(",")[0].strip().rstrip("s") if desc else ""
+        if d_first and d_first in q_tokens:
+            score += 1.0
+            
+        if "raw" in desc:
+            score += 0.5
+            
+        bad_keywords = ["patty", "chips", "rings", "fried", "powder", "salad", "frozen"]
+        if any(w in desc for w in bad_keywords):
+            score -= 3.0
+            
+        return score
+
+    def _select_best_food(self, foods, query: str):
+        if not foods:
+            return None
+        return max(foods, key=lambda f: self._score_food(f, query))
+
+    async def get_nutrition(self, ingredient_name: str):
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                response = await client.get(
+                    self.base_url,
+                    params={
+                        "query": ingredient_name,
+                        "pageSize": 10,
+                        "api_key": self.api_key,
+                        "dataType": "SR Legacy,Foundation",
+                    },
+                )
+
+                response.raise_for_status()
+
+                data = response.json()
+
+                foods = data.get("foods", [])
+
+                if not foods:
+                    return None
+
+                food = self._select_best_food(foods, ingredient_name)
+
+                if not food:
+                    return None
+
+                print(
+                    f"[NutritionService] '{ingredient_name}' matched to '{food.get('description')}'"
+                )
+
+                nutrients = {
+                    n["nutrientName"]: n["value"]
+                    for n in food.get("foodNutrients", [])
+                    if "value" in n
+                }
+
+                return {
+                    "calories": (
+                        nutrients.get("Energy")
+                        or nutrients.get("Energy (Atwater General Factors)")
+                        or nutrients.get("Energy (Atwater Specific Factors)")
+                        or 0
+                    ),
+                    "protein": nutrients.get("Protein", 0),
+                    "carbs": nutrients.get("Carbohydrate, by difference", 0),
+                    "fat": nutrients.get("Total lipid (fat)", 0),
+                }
+
+        except Exception as e:
+            print(f"[NutritionService] {ingredient_name}: {e}")
+            return None
+    def _safe_float(self, value):
+        try:
+            return float(value)
+        except Exception:
+            return 0.0
+
+    async def calculate_recipe_nutrition(
+        self,
+        ingredients,
+        servings,
+    ):
+        total_calories = 0.0
+        total_protein = 0.0
+        total_carbs = 0.0
+        total_fat = 0.0
+
+        for ingredient in ingredients:
+
+            name = ingredient.get("name", "")
+
+            quantity = self._safe_float(
+                ingredient.get("quantity", 0)
+            )
+
+            unit = (
+                ingredient.get("unit", "")
+                .lower()
+                .strip()
+            )
+
+            print(f"CHECKING USDA FOR: {name}")
+
+            # TEMP DEBUG
+            # if unit not in ["g", "gm", "gram", "grams"]:
+            #     continue
+
+            nutrition = await self.get_nutrition(name)
+
+            if not nutrition:
+                continue
+
+            multiplier = quantity / 100.0
+
+            total_calories += nutrition["calories"] * multiplier
+            total_protein += nutrition["protein"] * multiplier
+            total_carbs += nutrition["carbs"] * multiplier
+            total_fat += nutrition["fat"] * multiplier
+
+        servings = max(1, servings)
+
+        return {
+            "total": {
+                "calories": round(total_calories, 1),
+                "protein": round(total_protein, 1),
+                "carbs": round(total_carbs, 1),
+                "fat": round(total_fat, 1),
+            },
+            "per_serving": {
+                "calories": round(total_calories / servings, 1),
+                "protein": round(total_protein / servings, 1),
+                "carbs": round(total_carbs / servings, 1),
+                "fat": round(total_fat / servings, 1),
+            },
+        }        

app/services/object_detector.py

@@ -0,0 +1,199 @@
+import io
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+from huggingface_hub import hf_hub_download
+from ..config import (
+    YOLO_MODEL_ID,
+    YOLO_MODEL_FILENAME,
+    INTRA_OP_NUM_THREADS,
+    INTER_OP_NUM_THREADS,
+)
+
+print(f"Loading YOLO detector '{YOLO_MODEL_ID}/{YOLO_MODEL_FILENAME}'...")
+yolo_model_file = hf_hub_download(repo_id=YOLO_MODEL_ID, filename=YOLO_MODEL_FILENAME)
+
+yolo_ort_options = ort.SessionOptions()
+yolo_ort_options.intra_op_num_threads = INTRA_OP_NUM_THREADS
+yolo_ort_options.inter_op_num_threads = INTER_OP_NUM_THREADS
+yolo_session = ort.InferenceSession(
+    yolo_model_file, sess_options=yolo_ort_options, providers=["CPUExecutionProvider"]
+)
+print("YOLO detector loaded successfully!")
+
+
+def _letterbox(
+    img: Image.Image, new_shape: tuple[int, int] = (640, 640)
+) -> tuple[Image.Image, float, tuple[int, int]]:
+    """Resize image with letterboxing (preserve aspect ratio, pad with gray)."""
+    w, h = img.size
+    r = min(new_shape[0] / h, new_shape[1] / w)
+    new_unpad = (int(round(w * r)), int(round(h * r)))
+    dw = (new_shape[1] - new_unpad[0]) / 2
+    dh = (new_shape[0] - new_unpad[1]) / 2
+
+    resized = img.resize(new_unpad, Image.Resampling.BILINEAR)
+
+    top, bottom = int(round(dh - 0.1)), int(round(dh + 0.1))
+    left, right = int(round(dw - 0.1)), int(round(dw + 0.1))
+    padded = Image.new("RGB", (new_shape[1], new_shape[0]), (114, 114, 114))
+    padded.paste(resized, (left, top))
+    return padded, r, (dw, dh)
+
+
+def _nms(boxes: np.ndarray, scores: np.ndarray, iou_threshold: float) -> np.ndarray:
+    """Non-Maximum Suppression. Returns indices of kept boxes."""
+    if len(boxes) == 0:
+        return np.array([], dtype=int)
+
+    order = scores.argsort()[::-1]
+    keep = []
+
+    while len(order) > 0:
+        i = order[0]
+        keep.append(i)
+        if len(order) == 1:
+            break
+
+        xx1 = np.maximum(boxes[i, 0], boxes[order[1:], 0])
+        yy1 = np.maximum(boxes[i, 1], boxes[order[1:], 1])
+        xx2 = np.minimum(boxes[i, 2], boxes[order[1:], 2])
+        yy2 = np.minimum(boxes[i, 3], boxes[order[1:], 3])
+
+        inter = np.maximum(0, xx2 - xx1) * np.maximum(0, yy2 - yy1)
+        area_i = (boxes[i, 2] - boxes[i, 0]) * (boxes[i, 3] - boxes[i, 1])
+        area_rest = (boxes[order[1:], 2] - boxes[order[1:], 0]) * (
+            boxes[order[1:], 3] - boxes[order[1:], 1]
+        )
+        iou = inter / (area_i + area_rest - inter + 1e-7)
+
+        inds = np.where(iou <= iou_threshold)[0]
+        order = order[inds + 1]
+
+    return np.array(keep, dtype=int)
+
+
+def _preprocess(contents: bytes) -> tuple[np.ndarray, float, tuple[int, int], tuple[int, int]]:
+    """Decode image, letterbox to 640x640, return NCHW float32 tensor + metadata."""
+    image = Image.open(io.BytesIO(contents)).convert("RGB")
+    orig_w, orig_h = image.size
+
+    img, ratio, (dw, dh) = _letterbox(image)
+    arr = np.array(img, dtype=np.float32) / 255.0
+    arr = arr.transpose(2, 0, 1)  # HWC -> CHW
+    arr = np.expand_dims(arr, 0)  # add batch dim -> NCHW
+    return arr, ratio, (dw, dh), (orig_w, orig_h)
+
+
+def _postprocess(
+    output: np.ndarray,
+    conf_threshold: float,
+    iou_threshold: float,
+    ratio: float,
+    pad: tuple[int, int],
+    orig_size: tuple[int, int],
+    max_detections: int,
+) -> list[dict]:
+    """Parse YOLO output tensor, apply NMS, return list of detections."""
+    # output shape: (1, 84, 8400) -> transpose to (8400, 84)
+    preds = output[0].T  # (8400, 84)
+
+    boxes_xywh = preds[:, :4]
+    class_scores = preds[:, 4:]
+    max_scores = class_scores.max(axis=1)
+    class_ids = class_scores.argmax(axis=1)
+
+    # Filter by confidence
+    mask = max_scores > conf_threshold
+    boxes_xywh = boxes_xywh[mask]
+    max_scores = max_scores[mask]
+    class_ids = class_ids[mask]
+
+    if len(max_scores) == 0:
+        return []
+
+    # Convert xywh -> xyxy
+    x1 = boxes_xywh[:, 0] - boxes_xywh[:, 2] / 2
+    y1 = boxes_xywh[:, 1] - boxes_xywh[:, 3] / 2
+    x2 = boxes_xywh[:, 0] + boxes_xywh[:, 2] / 2
+    y2 = boxes_xywh[:, 1] + boxes_xywh[:, 3] / 2
+    boxes_xyxy = np.stack([x1, y1, x2, y2], axis=1)
+
+    # NMS
+    keep = _nms(boxes_xyxy, max_scores, iou_threshold)
+
+    # Take top max_detections
+    if len(keep) > max_detections:
+        keep = keep[:max_detections]
+
+    # Scale back to original image coordinates (undo letterbox padding + ratio)
+    dw, dh = pad
+    orig_w, orig_h = orig_size
+    detections = []
+    for idx in keep:
+        bx1, by1, bx2, by2 = boxes_xyxy[idx]
+        # Undo letterbox padding
+        bx1 = (bx1 - dw) / ratio
+        by1 = (by1 - dh) / ratio
+        bx2 = (bx2 - dw) / ratio
+        by2 = (by2 - dh) / ratio
+        # Clamp to original image bounds
+        bx1 = max(0, min(bx1, orig_w))
+        by1 = max(0, min(by1, orig_h))
+        bx2 = max(0, min(bx2, orig_w))
+        by2 = max(0, min(by2, orig_h))
+        detections.append(
+            {
+                "bbox": [float(bx1), float(by1), float(bx2), float(by2)],
+                "confidence": float(max_scores[idx]),
+                "class_id": int(class_ids[idx]),
+            }
+        )
+
+    return detections
+
+
+def detect_objects(
+    contents: bytes,
+    conf_threshold: float = 0.25,
+    iou_threshold: float = 0.45,
+    max_detections: int = 3,
+) -> list[dict]:
+    """Run YOLO detection on image bytes. Returns list of detections sorted by confidence."""
+    pixel_values, ratio, pad, orig_size = _preprocess(contents)
+    input_name = yolo_session.get_inputs()[0].name
+    output_name = yolo_session.get_outputs()[0].name
+    raw_output = yolo_session.run([output_name], {input_name: pixel_values})[0]
+    detections = _postprocess(
+        raw_output, conf_threshold, iou_threshold, ratio, pad, orig_size, max_detections
+    )
+    return detections
+
+
+def crop_objects(
+    contents: bytes, detections: list[dict], padding_ratio: float = 0.10
+) -> list[bytes]:
+    """Crop detected bounding box regions from the original image. Returns list of JPEG bytes."""
+    image = Image.open(io.BytesIO(contents)).convert("RGB")
+    orig_w, orig_h = image.size
+    crops = []
+
+    for det in detections:
+        x1, y1, x2, y2 = det["bbox"]
+        bw, bh = x2 - x1, y2 - y1
+        pad_x, pad_y = bw * padding_ratio, bh * padding_ratio
+
+        cx1 = max(0, int(x1 - pad_x))
+        cy1 = max(0, int(y1 - pad_y))
+        cx2 = min(orig_w, int(x2 + pad_x))
+        cy2 = min(orig_h, int(y2 + pad_y))
+
+        if cx2 <= cx1 or cy2 <= cy1:
+            continue
+
+        crop = image.crop((cx1, cy1, cx2, cy2))
+        buf = io.BytesIO()
+        crop.save(buf, format="JPEG", quality=95)
+        crops.append(buf.getvalue())
+
+    return crops

app/services/quantity_normalizer_service.py

@@ -0,0 +1,625 @@
+"""
+QuantityNormalizerService
+=========================
+Converts recipe cooking-unit ingredients → grams using USDA FoodData Central.
+
+Flow per ingredient:
+    1. Search /v1/foods/search  → fdcId
+    2. Fetch /v1/food/{fdcId}   → foodPortions + foodMeasures
+    3. Match cooking unit to a USDA portion entry
+    4. Return grams
+
+Design constraints honoured:
+    ✓ No hardcoded ingredient conversion tables
+    ✓ No extra LLM calls
+    ✓ USDA is the single source of truth
+    ✓ Returns None (never 0) when conversion impossible — caller skips
+"""
+
+import re
+import logging
+from difflib import SequenceMatcher
+from typing import Optional
+
+import httpx  # already in your stack; swap for aiohttp if preferred
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# USDA base URL — single constant, easy to mock in tests
+# ---------------------------------------------------------------------------
+USDA_BASE = "https://api.nal.usda.gov/fdc/v1"
+
+# ---------------------------------------------------------------------------
+# Unit alias table
+# Purpose: normalise user-facing cooking strings → a canonical key.
+# These are UNIT NAME normalisations only — no gram values here.
+# ---------------------------------------------------------------------------
+UNIT_ALIASES: dict[str, str] = {
+    # cups
+    "cup": "cup", "cups": "cup", "c": "cup", "c.": "cup",
+    # tablespoons
+    "tablespoon": "tablespoon", "tablespoons": "tablespoon",
+    "tbsp": "tablespoon", "tbsp.": "tablespoon", "tbs": "tablespoon",
+    "tb": "tablespoon",
+    # teaspoons
+    "teaspoon": "teaspoon", "teaspoons": "teaspoon",
+    "tsp": "teaspoon", "tsp.": "teaspoon",
+    # mass — handled directly, no USDA lookup needed
+    "gram": "gram", "grams": "gram", "g": "gram", "g.": "gram",
+    "kilogram": "kilogram", "kilograms": "kilogram", "kg": "kilogram",
+    # imperial mass
+    "ounce": "ounce", "ounces": "ounce", "oz": "ounce", "oz.": "ounce",
+    "pound": "pound", "pounds": "pound", "lb": "pound",
+    "lbs": "pound", "lb.": "pound",
+    # volume (liquid)
+    "milliliter": "milliliter", "milliliters": "milliliter",
+    "ml": "milliliter", "ml.": "milliliter",
+    "liter": "liter", "liters": "liter", "l": "liter",
+    "fluid ounce": "fluid_ounce", "fl oz": "fluid_ounce",
+    "fl. oz.": "fluid_ounce",
+    # cooking pieces — all resolved via USDA foodPortions
+    "clove": "clove", "cloves": "clove",
+    "piece": "piece", "pieces": "piece",
+    "whole": "whole",
+    "small": "small",
+    "medium": "medium",
+    "large": "large",
+    "extra large": "extra_large", "xl": "extra_large",
+    "slice": "slice", "slices": "slice",
+    "sprig": "sprig", "sprigs": "sprig",
+    "stalk": "stalk", "stalks": "stalk",
+    "bunch": "bunch", "bunches": "bunch",
+    "head": "head", "heads": "head",
+    "handful": "handful",
+    "can": "can", "cans": "can",
+    "package": "package", "packages": "package", "pkg": "package",
+    "strip": "strip", "strips": "strip",
+    "fillet": "fillet", "fillets": "fillet",
+    "breast": "breast", "thigh": "thigh", "leg": "leg",
+    "pinch": "pinch", "dash": "dash",
+}
+
+# ---------------------------------------------------------------------------
+# SI fallback — for mass/volume units that need no ingredient-specific data.
+# Used ONLY when USDA returns nothing useful.
+# ---------------------------------------------------------------------------
+SI_GRAMS: dict[str, float] = {
+    "gram":        1.0,
+    "kilogram":    1000.0,
+    "ounce":       28.3495,
+    "pound":       453.592,
+    "milliliter":  1.0,      # water-density assumption; fine for oils/broths
+    "liter":       1000.0,
+    "fluid_ounce": 29.5735,
+    "tablespoon":  14.7868,  # last-resort SI for liquids only
+    "teaspoon":    4.9289,   # last-resort SI for liquids only
+}
+
+# ---------------------------------------------------------------------------
+# Negligible units — nutritionally irrelevant; skip cleanly without warning
+# ---------------------------------------------------------------------------
+SKIP_UNITS = {"pinch", "dash", "to taste", "as needed", "a pinch"}
+
+
+# ===========================================================================
+class QuantityNormalizerService:
+    """
+    Async service.  Instantiate once, reuse across requests (shares httpx client).
+
+    Usage:
+        async with QuantityNormalizerService(api_key="...") as normalizer:
+            result = await normalizer.normalize_ingredient({
+                "name": "Basmati Rice",
+                "quantity": "1",
+                "unit": "cup"
+            })
+    """
+
+    def __init__(self, api_key: str):
+        self._api_key = api_key
+        self._client: Optional[httpx.AsyncClient] = None
+
+    # ------------------------------------------------------------------
+    # Context manager — keeps a single httpx session alive
+    # ------------------------------------------------------------------
+    async def __aenter__(self):
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(10.0),
+            params={"api_key": self._api_key},
+        )
+        return self
+
+    async def __aexit__(self, *_):
+        if self._client:
+            await self._client.aclose()
+
+    # ==================================================================
+    # Public API
+    # ==================================================================
+
+    async def normalize_ingredient(self, ingredient: dict) -> Optional[dict]:
+        """
+        Convert one ingredient dict to grams.
+
+        Input:
+            {"name": "Garlic", "quantity": "2", "unit": "cloves"}
+
+        Output (success):
+            {
+                "name": "Garlic",
+                "original_quantity": "2 cloves",
+                "quantity": 6.0,
+                "unit": "g"
+            }
+
+        Output (failure):
+            None   ← caller skips this ingredient, reason already logged
+        """
+        name         = ingredient.get("name", "").strip()
+        raw_quantity = str(ingredient.get("quantity", "0")).strip()
+        raw_unit     = str(ingredient.get("unit", "")).strip()
+
+        if not name:
+            logger.warning("normalize_ingredient: ingredient has no name — skipping")
+            return None
+
+        quantity = self._parse_quantity(raw_quantity)
+        if quantity is None or quantity <= 0:
+            logger.warning(
+                "[%s] quantity '%s' could not be parsed — skipping", name, raw_quantity
+            )
+            return None
+
+        canonical_unit = self._canonicalize(raw_unit)
+
+        # Negligible units — skip without noise
+        if canonical_unit in SKIP_UNITS:
+            logger.info("[%s] unit '%s' is negligible — skipping", name, raw_unit)
+            return None
+
+        original = f"{raw_quantity} {raw_unit}".strip()
+        logger.debug("[%s] normalising: %s", name, original)
+
+        # ── Path 1: already in grams / kg ──────────────────────────────────
+        if canonical_unit in ("gram", "kilogram"):
+            grams = quantity * SI_GRAMS[canonical_unit]
+            return self._result(name, original, grams)
+
+        # ── Path 2: USDA lookup ─────────────────────────────────────────────
+        grams = await self._usda_convert(name, quantity, canonical_unit, raw_unit)
+        if grams is not None:
+            return self._result(name, original, grams)
+
+        # ── Path 3: SI fallback (oz, lb, ml, l, fl oz) ─────────────────────
+        if canonical_unit in SI_GRAMS:
+            grams = quantity * SI_GRAMS[canonical_unit]
+            logger.info(
+                "[%s] SI fallback: %s %s → %.2fg", name, quantity, raw_unit, grams
+            )
+            return self._result(name, original, grams)
+
+        # ── No conversion possible ──────────────────────────────────────────
+        logger.warning(
+            "[%s] SKIP — cannot convert '%s %s': "
+            "no USDA portion match and no SI fallback for this unit.",
+            name, quantity, raw_unit,
+        )
+        return None
+
+    async def normalize_ingredients(
+        self, ingredients: list[dict]
+    ) -> tuple[list[dict], list[dict]]:
+        """
+        Normalise a list of ingredients.
+
+        Returns (normalised, skipped) — two separate lists so the caller
+        can log or surface skipped items to the user.
+        """
+        import asyncio
+        tasks = [self.normalize_ingredient(i) for i in ingredients]
+        results = await asyncio.gather(*tasks, return_exceptions=False)
+
+        normalised, skipped = [], []
+        for original, result in zip(ingredients, results):
+            if result is None:
+                skipped.append(original)
+            else:
+                normalised.append(result)
+
+        print("\n===== NORMALIZED INGREDIENTS =====")
+        for item in normalised:
+            print(item)
+
+        print("\n===== SKIPPED INGREDIENTS =====")
+        for item in skipped:
+            print(item)
+
+        print("=================================\n")
+
+        return normalised, skipped
+
+    # ==================================================================
+    # USDA logic
+    # ==================================================================
+
+    async def _usda_convert(
+        self,
+        name: str,
+        quantity: float,
+        canonical_unit: str,
+        raw_unit: str,
+    ) -> Optional[float]:
+        """
+        Full USDA two-step:
+            1. Search → fdcId
+            2. Food detail → foodPortions + foodMeasures
+            3. Match unit → gramWeight
+        """
+        fdc_id = await self._search_fdc_id(name)
+        if fdc_id is None:
+            logger.warning("[%s] USDA search returned no results", name)
+            return None
+
+        portions, measures = await self._fetch_portions(fdc_id, name)
+
+        # Try foodPortions first (richer, from /food/{fdcId})
+        gw = self._match_portions(canonical_unit, portions)
+        if gw is not None:
+            result = quantity * gw
+            logger.debug(
+                "[%s] foodPortions match: %s %s → %.2fg (%.4g g/unit)",
+                name, quantity, raw_unit, result, gw,
+            )
+            return result
+
+        # Fall back to foodMeasures (also present on detail endpoint)
+        gw = self._match_measures(canonical_unit, measures)
+        if gw is not None:
+            result = quantity * gw
+            logger.debug(
+                "[%s] foodMeasures match: %s %s → %.2fg (%.4g g/unit)",
+                name, quantity, raw_unit, result, gw,
+            )
+            return result
+
+        logger.info(
+            "[%s] fdcId=%s — no portion/measure match for unit '%s'. "
+            "Available: portions=%s  measures=%s",
+            name, fdc_id,
+            canonical_unit,
+            [p.get("modifier","") or p.get("measureUnit",{}).get("name","") for p in portions],
+            [m.get("disseminationText","") for m in measures],
+        )
+        return None
+
+    async def _search_fdc_id(self, query: str) -> Optional[int]:
+        """Search USDA, return fdcId of best SR Legacy / Foundation match.
+
+        Uses pageSize=100 and scores results so that SR Legacy/Foundation entries for
+        raw/whole foods rank above processed or branded items that happen
+        to share a keyword (e.g. "Rice crackers" vs "Rice, white, raw").
+        """
+        # Generic query sanitization: regex-remove parenthetical text and trim
+        query = re.sub(r"\(.*?\)", "", query).strip()
+        query = re.sub(r"\s+", " ", query)
+
+        _PROCESSED_KW = {
+            "cracker", "snack", "cake", "cookie", "chip", "mix", "beverage",
+            "soup", "sauce", "pudding", "babyfood", "ring", "frozen", "fried",
+            "powder", "flake", "dehydrated", "pickled", "canned", "bread",
+            "breadstick", "sausage",
+        }
+
+        def _score(food: dict, q_str: str) -> float:
+            desc  = food.get("description", "").lower()
+            q_low = q_str.lower()
+            sc    = SequenceMatcher(None, q_low, desc).ratio()
+            # Bonus: description starts with a query word ("Onions, raw" for "Onion")
+            q_stems = {w.rstrip("s") for w in q_low.split()}
+            d_first = desc.split(",")[0].strip().rstrip("s") if desc else ""
+            if d_first and d_first in q_stems:
+                sc += 1.0
+                if "," in desc[:15]:   # "Onions, raw" pattern — tightly scoped entry
+                    sc += 2.0
+            # Bonus: raw / whole food
+            if any(w in desc for w in ("raw", "fresh", "uncooked")):
+                sc += 0.5
+            # SR Legacy has richer foodPortions than Foundation
+            if food.get("dataType") == "SR Legacy":
+                sc += 2.0
+            # Penalty: processed / packaged food
+            for kw in _PROCESSED_KW:
+                if kw in desc:
+                    sc -= 3.0
+                    break
+            return sc
+
+        # Formulate search queries: try appending "raw" first if not specified
+        queries = [query]
+        q_low = query.lower()
+        if not any(w in q_low for w in ("raw", "fresh", "uncooked", "cooked", "dry", "canned", "powder")):
+            queries.insert(0, f"{query} raw")
+
+        for q in queries:
+            try:
+                resp = await self._client.get(
+                    f"{USDA_BASE}/foods/search",
+                    params={
+                        "query":    q,
+                        "dataType": "SR Legacy,Foundation",
+                        "pageSize": 100,
+                    },
+                )
+                resp.raise_for_status()
+                foods = resp.json().get("foods", [])
+                if foods:
+                    best = max(foods, key=lambda f: _score(f, q))
+                    return best.get("fdcId")
+            except httpx.HTTPError as exc:
+                logger.error("[%s] USDA search HTTP error for query '%s': %s", query, q, exc)
+        return None
+
+    async def _fetch_portions(
+        self, fdc_id: int, name: str
+    ) -> tuple[list[dict], list[dict]]:
+        """
+        Fetch /v1/food/{fdcId}.
+        Returns (foodPortions, foodMeasures) — both may be empty lists.
+        """
+        try:
+            resp = await self._client.get(f"{USDA_BASE}/food/{fdc_id}")
+            resp.raise_for_status()
+            data = resp.json()
+            portions = data.get("foodPortions", [])
+            measures = data.get("foodMeasures", [])
+            logger.debug(
+                "[%s] fdcId=%s  portions=%d  measures=%d",
+                name, fdc_id, len(portions), len(measures),
+            )
+            return portions, measures
+        except httpx.HTTPError as exc:
+            logger.error("[%s] USDA detail HTTP error (fdcId=%s): %s", name, fdc_id, exc)
+            return [], []
+
+    # ==================================================================
+    # Matching logic
+    # ==================================================================
+
+    def _match_portions(
+        self, canonical_unit: str, portions: list[dict]
+    ) -> Optional[float]:
+        """
+        Match against foodPortions (from /food/{fdcId}).
+
+        foodPortions entry shape:
+        {
+            "id": 123,
+            "amount": 1.0,
+            "gramWeight": 186.0,
+            "modifier": "1 cup",               ← free-text description
+            "measureUnit": {
+                "id": 999,
+                "name": "cup",                  ← structured unit name
+                "abbreviation": "cup"
+            },
+            "portionDescription": "1 cup"
+        }
+        """
+        best_score = -1.0
+        best_gw: Optional[float] = None
+        size_units = {'small', 'medium', 'large', 'whole', 'piece'}
+        penalized_keywords = ['slice', 'sliced', 'chopped', 'diced', 'rings']
+
+        for portion in portions:
+            gw     = portion.get("gramWeight")
+            amount = portion.get("amount") or 1.0
+            if not gw or gw <= 0 or not amount:
+                continue
+
+            # Gather candidate text fields for this portion
+            candidates = self._portion_text_candidates(portion)
+
+            for text in candidates:
+                if not text:
+                    continue
+                usda_canonical = self._canonicalize(text)
+
+                # Exact match — done
+                if usda_canonical == canonical_unit:
+                    score = 1.0
+                # Substring match — "medium onion" contains "medium"
+                elif canonical_unit in usda_canonical or usda_canonical in canonical_unit:
+                    score = 0.9
+                else:
+                    score = SequenceMatcher(None, canonical_unit, usda_canonical).ratio()
+
+                # Adjust portion ranking: favor whole-item/each portions when input unit is medium/whole
+                if canonical_unit in size_units:
+                    if any(x in usda_canonical for x in penalized_keywords):
+                        score -= 0.4
+                    if any(x in usda_canonical for x in (canonical_unit, "whole", "each")):
+                        score += 0.05
+
+                if score > best_score and score >= 0.78:
+                    best_score = score
+                    best_gw = gw / amount
+
+        return best_gw
+
+    def _match_measures(
+        self, canonical_unit: str, measures: list[dict]
+    ) -> Optional[float]:
+        """
+        Match against foodMeasures (also present on /food/{fdcId}).
+
+        foodMeasures entry shape:
+        {
+            "disseminationText": "1 cup",
+            "gramWeight": 186.0,
+            "id": 456,
+            "measureUnitAbbreviation": "cup",
+            "measureUnitName": "cup",
+            "rank": 1
+        }
+        """
+        best_score = 0.0
+        best_gw: Optional[float] = None
+
+        for measure in measures:
+            gw    = measure.get("gramWeight")
+            dissem = measure.get("disseminationText", "")
+            if not gw or gw <= 0 or not dissem:
+                continue
+
+            usda_qty, usda_unit_raw = self._parse_usda_dissem(dissem)
+            if not usda_qty or usda_qty <= 0:
+                continue
+
+            usda_canonical = self._canonicalize(usda_unit_raw)
+
+            if usda_canonical == canonical_unit:
+                return gw / usda_qty
+
+            if canonical_unit in usda_canonical or usda_canonical in canonical_unit:
+                score = 0.9
+            else:
+                score = SequenceMatcher(None, canonical_unit, usda_canonical).ratio()
+
+            if score > best_score and score >= 0.78:
+                best_score = score
+                best_gw = gw / usda_qty
+
+        return best_gw
+
+    # ==================================================================
+    # Parsing helpers
+    # ==================================================================
+
+    @staticmethod
+    def _portion_text_candidates(portion: dict) -> list[str]:
+        """
+        Extract all text fields from a foodPortions entry that might
+        describe the unit — in priority order.
+        """
+        candidates = []
+
+        # Structured unit name (most reliable)
+        mu = portion.get("measureUnit") or {}
+        if mu.get("name") and mu["name"].lower() != "undetermined":
+            candidates.append(mu["name"])
+        if mu.get("abbreviation") and mu["abbreviation"].lower() != "undetermined":
+            candidates.append(mu["abbreviation"])
+
+        # Free-text modifier: "1 cup", "medium", "1 NLEA serving"
+        modifier = portion.get("modifier", "")
+        if modifier:
+            # Strip leading quantity if present ("1 cup" → "cup")
+            clean = re.sub(r"^\d+[\./]?\d*\s*", "", modifier).strip()
+            candidates.append(clean)
+            candidates.append(modifier)  # also try full string
+
+        # portionDescription as last resort
+        desc = portion.get("portionDescription", "")
+        if desc:
+            clean = re.sub(r"^\d+[\./]?\d*\s*", "", desc).strip()
+            candidates.append(clean)
+
+        return [c.strip().lower() for c in candidates if c.strip()]
+
+    @staticmethod
+    def _parse_usda_dissem(text: str) -> tuple[Optional[float], str]:
+        """
+        Parse USDA disseminationText.
+
+        "1 cup"        → (1.0, "cup")
+        "1/2 teaspoon" → (0.5, "teaspoon")
+        "3 cloves"     → (3.0, "cloves")
+        "medium"       → (1.0, "medium")   ← no leading number
+        """
+        text = text.strip()
+        match = re.match(r"^(\d+(?:\.\d+)?|\d+/\d+)\s+(.*)", text)
+        if not match:
+            # No leading number — treat whole string as unit name, qty=1
+            return 1.0, text
+
+        qty_str, unit_str = match.group(1), match.group(2).strip()
+        if "/" in qty_str:
+            try:
+                num, den = qty_str.split("/", 1)
+                qty = float(num) / float(den)
+            except (ValueError, ZeroDivisionError):
+                return None, unit_str
+        else:
+            try:
+                qty = float(qty_str)
+            except ValueError:
+                return None, unit_str
+
+        return qty, unit_str
+
+    @staticmethod
+    def _parse_quantity(raw: str) -> Optional[float]:
+        """
+        Parse a quantity string to float.
+
+        "1"     → 1.0
+        "1.5"   → 1.5
+        "1/2"   → 0.5
+        "½"     → 0.5
+        "2 cup" → 2.0   (leading number extracted)
+        """
+        UNICODE_FRACTIONS = {
+            "½": "1/2", "⅓": "1/3", "⅔": "2/3",
+            "¼": "1/4", "¾": "3/4", "⅛": "1/8",
+        }
+        for char, repl in UNICODE_FRACTIONS.items():
+            raw = raw.replace(char, repl)
+
+        match = re.match(r"^(\d+(?:\.\d+)?|\d+/\d+)", raw.strip())
+        if not match:
+            return None
+
+        qty_str = match.group(1)
+        if "/" in qty_str:
+            try:
+                num, den = qty_str.split("/", 1)
+                return float(num) / float(den)
+            except (ValueError, ZeroDivisionError):
+                return None
+        try:
+            return float(qty_str)
+        except ValueError:
+            return None
+
+    @staticmethod
+    def _canonicalize(unit: str) -> str:
+        """
+        'Tbsp.'   → 'tablespoon'
+        'CLOVES'  → 'clove'
+        '1 cup'   → 'cup'          (leading quantity stripped before alias lookup)
+        '1 tsp'   → 'teaspoon'     (strip number, then alias tsp→teaspoon)
+        '3 cloves'→ 'clove'        (strip number, strip trailing s)
+        'medium onion' → try alias, fall back to lowercased string
+        """
+        cleaned = unit.strip().lower()
+        # Strip leading integer/fraction quantity ("1 ", "1/2 ", "0.25 ") so
+        # USDA modifier strings like "1 cup" or "3 cloves" resolve via the alias table.
+        stripped_qty = re.sub(r"^\d+(?:[./]\d+)?\s+", "", cleaned).strip()
+        # Try each form: number-stripped first (most specific), then with number
+        for candidate in (stripped_qty, cleaned):
+            if candidate in UNIT_ALIASES:
+                return UNIT_ALIASES[candidate]
+            without_suffix = candidate.rstrip(".").rstrip("s")
+            if without_suffix in UNIT_ALIASES:
+                return UNIT_ALIASES[without_suffix]
+        return stripped_qty or cleaned
+
+    @staticmethod
+    def _result(name: str, original: str, grams: float) -> dict:
+        return {
+            "name":              name,
+            "original_quantity": original,
+            "quantity":          round(grams, 4),
+            "unit":              "g",
+        }

app/services/supabase.py

@@ -0,0 +1,72 @@
+import os
+import httpx
+from .http_client import http_client
+
+class SupabaseQuerier:
+    def __init__(self, url: str = None, key: str = None):
+        self.url = url or os.environ.get("SUPABASE_URL", "")
+        self.key = key or os.environ.get("SUPABASE_ANON_KEY", "")
+
+    async def get_product_by_slug(self, slug: str) -> dict | None:
+        if not self.url or not self.key:
+            print("[SupabaseQuerier] Warning: Supabase credentials missing.")
+            return None
+
+        base_url = self.url.rstrip("/")
+        query_url = f"{base_url}/rest/v1/inventory?slug=eq.{slug}&select=sku,slug,name,price_rupees,staging_dirs"
+        
+        headers = {
+            "apikey": self.key,
+            "Authorization": f"Bearer {self.key}"
+        }
+
+        client = http_client if http_client is not None else httpx.AsyncClient()
+        close_client = http_client is None
+        try:
+            response = await client.get(query_url, headers=headers, timeout=5.0)
+            if response.status_code == 200:
+                data = response.json()
+                if isinstance(data, list) and len(data) > 0:
+                    return data[0]
+            else:
+                print(f"[SupabaseQuerier] Query failed: {response.status_code} - {response.text}")
+        except Exception as e:
+            print(f"[SupabaseQuerier] Error querying Supabase: {e}")
+        finally:
+            if close_client:
+                await client.aclose()
+        return None
+
+    async def get_order_history(self, user_id: str, days: int = 90) -> list:
+        if not self.url or not self.key:
+            print("[SupabaseQuerier] Warning: Supabase credentials missing.")
+            return []
+
+        from datetime import datetime, timedelta
+        cutoff_date = (datetime.utcnow() - timedelta(days=days)).isoformat()
+
+        base_url = self.url.rstrip("/")
+        query_url = f"{base_url}/rest/v1/user_carts?user_id=eq.{user_id}&status=eq.processed&created_at=gte.{cutoff_date}&select=items,created_at"
+        
+        headers = {
+            "apikey": self.key,
+            "Authorization": f"Bearer {self.key}"
+        }
+
+        client = http_client if http_client is not None else httpx.AsyncClient()
+        close_client = http_client is None
+        try:
+            print(f"DEBUG: Query URL: {query_url}")
+            response = await client.get(query_url, headers=headers, timeout=5.0)
+            print(f"DEBUG: Status Code: {response.status_code}")
+            if response.status_code == 200:
+                print(f"DEBUG: Response length: {len(response.json())}")
+                return response.json()
+            else:
+                print(f"[SupabaseQuerier] Order history query failed: {response.status_code} - {response.text}")
+        except Exception as e:
+            print(f"[SupabaseQuerier] Error querying Supabase order history: {e}")
+        finally:
+            if close_client:
+                await client.aclose()
+        return []

app/utils/cart_state.py

@@ -0,0 +1,68 @@
+import threading
+from typing import Dict, Any, List
+
+class InMemoryCartStateManager:
+    def __init__(self):
+        # Dictionary structure: { user_id: { sku: quantity } }
+        self._carts: Dict[str, Dict[str, int]] = {}
+        self._lock = threading.Lock()
+
+    def sync_from_client(self, user_id: str, current_cart: List[Dict[str, Any]]) -> None:
+        """
+        Resets the server-side cart for a user to exactly match the authoritative
+        state sent by the Flutter client on every request.
+
+        Flutter's CartService is the single source of truth. This prevents the
+        server accumulating stale quantities when the cart is modified externally
+        (dashboard scanner, checkout, manual clear from outside the chatbot).
+        """
+        with self._lock:
+            if not current_cart:
+                # Cart was cleared externally — wipe server state entirely
+                self._carts[user_id] = {}
+            else:
+                # Rebuild map directly from client payload
+                self._carts[user_id] = {
+                    item["sku"]: int(item.get("quantity", 1))
+                    for item in current_cart
+                    if item.get("sku")
+                }
+
+    def add_item(self, user_id: str, sku: str, quantity: int = 1) -> bool:
+        """Thread-safe write operation to add or increment a SKU in a user's cart."""
+        with self._lock:
+            if user_id not in self._carts:
+                self._carts[user_id] = {}
+            
+            # Increment the quantity if it already exists, otherwise set it
+            current_qty = self._carts[user_id].get(sku, 0)
+            self._carts[user_id][sku] = current_qty + quantity
+            return True
+
+    def get_cart(self, user_id: str) -> Dict[str, int]:
+        """Thread-safe read operation to fetch a user's full cart map."""
+        with self._lock:
+            # Return a copy to prevent external mutation outside the lock
+            return dict(self._carts.get(user_id, {}))
+
+    def clear_cart(self, user_id: str) -> None:
+        """Thread-safe operation to wipe out a cart session."""
+        with self._lock:
+            if user_id in self._carts:
+                self._carts[user_id] = {}
+
+    def remove_item(self, user_id: str, sku: str, quantity: int = 1) -> bool:
+        """Thread-safe write operation to remove or decrement a SKU in a user's cart."""
+        with self._lock:
+            if user_id not in self._carts or sku not in self._carts[user_id]:
+                return False
+            
+            current_qty = self._carts[user_id][sku]
+            if current_qty > quantity:
+                self._carts[user_id][sku] = current_qty - quantity
+            else:
+                del self._carts[user_id][sku]
+            return True
+
+# Instantiate a single global singleton instance to be imported across modules
+live_cart_memory = InMemoryCartStateManager()

inventory.json

@@ -0,0 +1,521 @@
+{
+  "currency": "INR",
+  "pricing_note": "Approximate catalog prices for demo inventory; staging images do not include normalized pack sizes.",
+  "items": [
+    {
+      "sku": "QLS-0001",
+      "slug": "5-star-magic-health-drink-bournvita",
+      "name": "Bournvita 5 Star Magic Health Drink",
+      "price_rupees": 249,
+      "staging_dirs": [
+        "5-star-magic-health-drink-bournvita"
+      ]
+    },
+    {
+      "sku": "QLS-0002",
+      "slug": "air-freshener-ambi-pur",
+      "name": "Ambi Pur Air Freshener",
+      "price_rupees": 299,
+      "staging_dirs": [
+        "air-freshener-ambi-pur"
+      ]
+    },
+    {
+      "sku": "QLS-0003",
+      "slug": "almond-chocolate-bar-snickers",
+      "name": "Snickers Almond Chocolate Bar",
+      "price_rupees": 50,
+      "staging_dirs": [
+        "almond-chocolate-bar-snickers"
+      ]
+    },
+    {
+      "sku": "QLS-0004",
+      "slug": "american-style-cream-and-onion-chips-lays",
+      "name": "Lay's American Style Cream and Onion Chips",
+      "price_rupees": 20,
+      "staging_dirs": [
+        "american-style-cream-and-onion-chips-lays",
+        "american-style-cream-and-onion-chips-lays-2",
+        "american-style-cream-and-onion-chips-lays-3",
+        "american-style-cream-and-onion-chips-lays-4"
+      ]
+    },
+    {
+      "sku": "QLS-0005",
+      "slug": "car-air-freshener-jasmine-ambi-pur",
+      "name": "Ambi Pur Jasmine Car Air Freshener",
+      "price_rupees": 399,
+      "staging_dirs": [
+        "car-air-freshener-jasmine-ambi-pur"
+      ]
+    },
+    {
+      "sku": "QLS-0006",
+      "slug": "ceregrow-multigrain-cereal-nestle",
+      "name": "Nestle Ceregrow Multigrain Cereal",
+      "price_rupees": 365,
+      "staging_dirs": [
+        "ceregrow-multigrain-cereal-nestle",
+        "ceregrow-multigrain-cereal-nestle-2"
+      ]
+    },
+    {
+      "sku": "QLS-0007",
+      "slug": "cerelac-rice-nestle",
+      "name": "Nestle Cerelac Rice",
+      "price_rupees": 285,
+      "staging_dirs": [
+        "cerelac-rice-nestle"
+      ]
+    },
+    {
+      "sku": "QLS-0008",
+      "slug": "cerelac-wheat-apple-nestle",
+      "name": "Nestle Cerelac Wheat Apple",
+      "price_rupees": 325,
+      "staging_dirs": [
+        "cerelac-wheat-apple-nestle"
+      ]
+    },
+    {
+      "sku": "QLS-0009",
+      "slug": "cheez-puffs-cheetos",
+      "name": "Cheetos Cheez Puffs",
+      "price_rupees": 20,
+      "staging_dirs": [
+        "cheez-puffs-cheetos",
+        "cheez-puffs-cheetos-2"
+      ]
+    },
+    {
+      "sku": "QLS-0010",
+      "slug": "chicken-noodles-maggi",
+      "name": "Maggi Chicken Noodles",
+      "price_rupees": 15,
+      "staging_dirs": [
+        "chicken-noodles-maggi"
+      ]
+    },
+    {
+      "sku": "QLS-0011",
+      "slug": "chocolate-bar-mars",
+      "name": "Mars Chocolate Bar",
+      "price_rupees": 40,
+      "staging_dirs": [
+        "chocolate-bar-mars"
+      ]
+    },
+    {
+      "sku": "QLS-0012",
+      "slug": "chocolate-bar-snickers",
+      "name": "Snickers Chocolate Bar",
+      "price_rupees": 40,
+      "staging_dirs": [
+        "chocolate-bar-snickers"
+      ]
+    },
+    {
+      "sku": "QLS-0013",
+      "slug": "chocolate-bar-softer-bar",
+      "name": "Softer Bar Chocolate Bar",
+      "price_rupees": 30,
+      "staging_dirs": [
+        "chocolate-bar-softer-bar"
+      ]
+    },
+    {
+      "sku": "QLS-0014",
+      "slug": "chocos-crunchy-bites-coco-caramel-kelloggs",
+      "name": "Kellogg's Chocos Crunchy Bites Coco Caramel",
+      "price_rupees": 35,
+      "staging_dirs": [
+        "chocos-crunchy-bites-coco-caramel-kelloggs"
+      ]
+    },
+    {
+      "sku": "QLS-0015",
+      "slug": "classic-malt-health-drink-horlicks",
+      "name": "Horlicks Classic Malt Health Drink",
+      "price_rupees": 249,
+      "staging_dirs": [
+        "classic-malt-health-drink-horlicks"
+      ]
+    },
+    {
+      "sku": "QLS-0016",
+      "slug": "corn-flakes-original-kelloggs",
+      "name": "Kellogg's Corn Flakes Original",
+      "price_rupees": 195,
+      "staging_dirs": [
+        "corn-flakes-original-kelloggs",
+        "corn-flakes-original-kelloggs-2"
+      ]
+    },
+    {
+      "sku": "QLS-0017",
+      "slug": "dairy-milk-chocolate-cadbury",
+      "name": "Cadbury Dairy Milk Chocolate",
+      "price_rupees": 40,
+      "staging_dirs": [
+        "dairy-milk-chocolate-cadbury"
+      ]
+    },
+    {
+      "sku": "QLS-0018",
+      "slug": "dairy-milk-crispello-cadbury",
+      "name": "Cadbury Dairy Milk Crispello",
+      "price_rupees": 40,
+      "staging_dirs": [
+        "dairy-milk-crispello-cadbury"
+      ]
+    },
+    {
+      "sku": "QLS-0019",
+      "slug": "dairy-milk-roast-almond-cadbury",
+      "name": "Cadbury Dairy Milk Roast Almond",
+      "price_rupees": 50,
+      "staging_dirs": [
+        "dairy-milk-roast-almond-cadbury"
+      ]
+    },
+    {
+      "sku": "QLS-0020",
+      "slug": "disinfectant-surface-cleaner-lizol",
+      "name": "Lizol Disinfectant Surface Cleaner",
+      "price_rupees": 220,
+      "staging_dirs": [
+        "disinfectant-surface-cleaner-lizol"
+      ]
+    },
+    {
+      "sku": "QLS-0021",
+      "slug": "flushmatic-citrus-toilet-cleaner-harpic",
+      "name": "Harpic Flushmatic Citrus Toilet Cleaner",
+      "price_rupees": 99,
+      "staging_dirs": [
+        "flushmatic-citrus-toilet-cleaner-harpic"
+      ]
+    },
+    {
+      "sku": "QLS-0022",
+      "slug": "fuse-chocolate-bar-cadbury",
+      "name": "Cadbury Fuse Chocolate Bar",
+      "price_rupees": 40,
+      "staging_dirs": [
+        "fuse-chocolate-bar-cadbury"
+      ]
+    },
+    {
+      "sku": "QLS-0023",
+      "slug": "ginger-garlic-paste-aachi",
+      "name": "Aachi Ginger Garlic Paste",
+      "price_rupees": 80,
+      "staging_dirs": [
+        "ginger-garlic-paste-aachi"
+      ]
+    },
+    {
+      "sku": "QLS-0024",
+      "slug": "gold-standardised-milk-amul",
+      "name": "Amul Gold Standardised Milk",
+      "price_rupees": 37,
+      "staging_dirs": [
+        "gold-standardised-milk-amul"
+      ]
+    },
+    {
+      "sku": "QLS-0025",
+      "slug": "groundnut-oil-idhayam-mantra",
+      "name": "Idhayam Mantra Groundnut Oil",
+      "price_rupees": 250,
+      "staging_dirs": [
+        "groundnut-oil-idhayam-mantra"
+      ]
+    },
+    {
+      "sku": "QLS-0026",
+      "slug": "health-drink-2x-strength-bournvita",
+      "name": "Bournvita 2x Strength Health Drink",
+      "price_rupees": 275,
+      "staging_dirs": [
+        "health-drink-2x-strength-bournvita"
+      ]
+    },
+    {
+      "sku": "QLS-0027",
+      "slug": "health-drink-boost",
+      "name": "Boost Health Drink",
+      "price_rupees": 255,
+      "staging_dirs": [
+        "health-drink-boost",
+        "health-drink-boost-2",
+        "health-drink-boost-3"
+      ]
+    },
+    {
+      "sku": "QLS-0028",
+      "slug": "hot-and-spicy-korean-kimchi-noodles-geki",
+      "name": "Geki Hot and Spicy Korean Kimchi Noodles",
+      "price_rupees": 50,
+      "staging_dirs": [
+        "hot-and-spicy-korean-kimchi-noodles-geki"
+      ]
+    },
+    {
+      "sku": "QLS-0029",
+      "slug": "hot-and-sweet-tomato-chilli-sauce-maggi",
+      "name": "Maggi Hot and Sweet Tomato Chilli Sauce",
+      "price_rupees": 170,
+      "staging_dirs": [
+        "hot-and-sweet-tomato-chilli-sauce-maggi"
+      ]
+    },
+    {
+      "sku": "QLS-0030",
+      "slug": "indias-magic-masala-chips-lays",
+      "name": "Lay's India's Magic Masala Chips",
+      "price_rupees": 20,
+      "staging_dirs": [
+        "indias-magic-masala-chips-lays",
+        "indias-magic-masala-chips-lays-2"
+      ]
+    },
+    {
+      "sku": "QLS-0031",
+      "slug": "jasmine-mist-air-freshener-odonil",
+      "name": "Odonil Jasmine Mist Air Freshener",
+      "price_rupees": 99,
+      "staging_dirs": [
+        "jasmine-mist-air-freshener-odonil"
+      ]
+    },
+    {
+      "sku": "QLS-0032",
+      "slug": "kitkat-chunky-white-nestle",
+      "name": "Nestle KitKat Chunky White",
+      "price_rupees": 70,
+      "staging_dirs": [
+        "kitkat-chunky-white-nestle"
+      ]
+    },
+    {
+      "sku": "QLS-0033",
+      "slug": "lactogen-pro-1-nestle",
+      "name": "Nestle Lactogen Pro 1",
+      "price_rupees": 420,
+      "staging_dirs": [
+        "lactogen-pro-1-nestle"
+      ]
+    },
+    {
+      "sku": "QLS-0034",
+      "slug": "lactogen-pro-4-nestle",
+      "name": "Nestle Lactogen Pro 4",
+      "price_rupees": 440,
+      "staging_dirs": [
+        "lactogen-pro-4-nestle"
+      ]
+    },
+    {
+      "sku": "QLS-0035",
+      "slug": "milkybar-white-chocolate-nestle",
+      "name": "Nestle Milkybar White Chocolate",
+      "price_rupees": 20,
+      "staging_dirs": [
+        "milkybar-white-chocolate-nestle"
+      ]
+    },
+    {
+      "sku": "QLS-0036",
+      "slug": "multigrain-chocos-chhota-bheem-kelloggs",
+      "name": "Kellogg's Multigrain Chocos Chhota Bheem",
+      "price_rupees": 20,
+      "staging_dirs": [
+        "multigrain-chocos-chhota-bheem-kelloggs"
+      ]
+    },
+    {
+      "sku": "QLS-0037",
+      "slug": "multigrain-chocos-kelloggs",
+      "name": "Kellogg's Multigrain Chocos",
+      "price_rupees": 210,
+      "staging_dirs": [
+        "multigrain-chocos-kelloggs"
+      ]
+    },
+    {
+      "sku": "QLS-0038",
+      "slug": "oats-quaker",
+      "name": "Quaker Oats",
+      "price_rupees": 195,
+      "staging_dirs": [
+        "oats-quaker"
+      ]
+    },
+    {
+      "sku": "QLS-0039",
+      "slug": "power-pocket-rose-fresh-blossom-godrej-aer",
+      "name": "Godrej Aer Power Pocket Rose Fresh Blossom",
+      "price_rupees": 65,
+      "staging_dirs": [
+        "power-pocket-rose-fresh-blossom-godrej-aer"
+      ]
+    },
+    {
+      "sku": "QLS-0040",
+      "slug": "puffcorn-yummy-cheese-kurkure-playz",
+      "name": "Kurkure Playz Puffcorn Yummy Cheese",
+      "price_rupees": 20,
+      "staging_dirs": [
+        "puffcorn-yummy-cheese-kurkure-playz"
+      ]
+    },
+    {
+      "sku": "QLS-0041",
+      "slug": "refined-sunflower-oil-gold-winner",
+      "name": "Gold Winner Refined Sunflower Oil",
+      "price_rupees": 180,
+      "staging_dirs": [
+        "refined-sunflower-oil-gold-winner"
+      ]
+    },
+    {
+      "sku": "QLS-0042",
+      "slug": "rich-tomato-ketchup-maggi",
+      "name": "Maggi Rich Tomato Ketchup",
+      "price_rupees": 155,
+      "staging_dirs": [
+        "rich-tomato-ketchup-maggi"
+      ]
+    },
+    {
+      "sku": "QLS-0043",
+      "slug": "rolled-oats-disaano",
+      "name": "Disaano Rolled Oats",
+      "price_rupees": 199,
+      "staging_dirs": [
+        "rolled-oats-disaano"
+      ]
+    },
+    {
+      "sku": "QLS-0044",
+      "slug": "room-spray-odonil",
+      "name": "Odonil Room Spray",
+      "price_rupees": 179,
+      "staging_dirs": [
+        "room-spray-odonil"
+      ]
+    },
+    {
+      "sku": "QLS-0045",
+      "slug": "shampoo-hair-colour-godrej-selfie",
+      "name": "Godrej Selfie Shampoo Hair Colour",
+      "price_rupees": 30,
+      "staging_dirs": [
+        "shampoo-hair-colour-godrej-selfie"
+      ]
+    },
+    {
+      "sku": "QLS-0046",
+      "slug": "similac-classic-stage-1-abbott",
+      "name": "Abbott Similac Classic Stage 1",
+      "price_rupees": 430,
+      "staging_dirs": [
+        "similac-classic-stage-1-abbott"
+      ]
+    },
+    {
+      "sku": "QLS-0047",
+      "slug": "spanish-tomato-tango-chips-lays",
+      "name": "Lay's Spanish Tomato Tango Chips",
+      "price_rupees": 20,
+      "staging_dirs": [
+        "spanish-tomato-tango-chips-lays",
+        "spanish-tomato-tango-chips-lays-2"
+      ]
+    },
+    {
+      "sku": "QLS-0048",
+      "slug": "spicy-manchurian-cuppa-noodles-maggi",
+      "name": "Maggi Spicy Manchurian Cuppa Noodles",
+      "price_rupees": 50,
+      "staging_dirs": [
+        "spicy-manchurian-cuppa-noodles-maggi"
+      ]
+    },
+    {
+      "sku": "QLS-0049",
+      "slug": "super-muesli-zero-added-sugar-yoga-bar",
+      "name": "Yoga Bar Super Muesli Zero Added Sugar",
+      "price_rupees": 349,
+      "staging_dirs": [
+        "super-muesli-zero-added-sugar-yoga-bar"
+      ]
+    },
+    {
+      "sku": "QLS-0050",
+      "slug": "sweet-chilli-hot-sauce-veeba",
+      "name": "Veeba Sweet Chilli Hot Sauce",
+      "price_rupees": 149,
+      "staging_dirs": [
+        "sweet-chilli-hot-sauce-veeba"
+      ]
+    },
+    {
+      "sku": "QLS-0051",
+      "slug": "sweet-onion-sauce-veeba",
+      "name": "Veeba Sweet Onion Sauce",
+      "price_rupees": 149,
+      "staging_dirs": [
+        "sweet-onion-sauce-veeba"
+      ]
+    },
+    {
+      "sku": "QLS-0052",
+      "slug": "synthetic-vinegar-double-horse",
+      "name": "Double Horse Synthetic Vinegar",
+      "price_rupees": 55,
+      "staging_dirs": [
+        "synthetic-vinegar-double-horse"
+      ]
+    },
+    {
+      "sku": "QLS-0053",
+      "slug": "taj-mahal-tea-brooke-bond",
+      "name": "Brooke Bond Taj Mahal Tea",
+      "price_rupees": 260,
+      "staging_dirs": [
+        "taj-mahal-tea-brooke-bond"
+      ]
+    },
+    {
+      "sku": "QLS-0054",
+      "slug": "thermosteel-water-bottle-milton",
+      "name": "Milton Thermosteel Water Bottle",
+      "price_rupees": 899,
+      "staging_dirs": [
+        "thermosteel-water-bottle-milton"
+      ]
+    },
+    {
+      "sku": "QLS-0055",
+      "slug": "tomato-sauce-happy",
+      "name": "Happy Tomato Sauce",
+      "price_rupees": 110,
+      "staging_dirs": [
+        "tomato-sauce-happy"
+      ]
+    },
+    {
+      "sku": "QLS-0056",
+      "slug": "womens-plus-caramel-horlicks",
+      "name": "Horlicks Women's Plus Caramel",
+      "price_rupees": 320,
+      "staging_dirs": [
+        "womens-plus-caramel-horlicks",
+        "womens-plus-caramel-horlicks-2"
+      ]
+    }
+  ]
+}

requirements.txt

@@ -0,0 +1,12 @@
+fastapi==0.111.0
+uvicorn==0.30.1
+python-multipart==0.0.9
+onnxruntime==1.19.2
+huggingface-hub==0.23.4
+transformers==4.41.2
+pillow==10.3.0
+httpx==0.27.0
+groq>=1.4.0
+python-dotenv>=1.0.0
+pydantic>=2.0.0
+numpy>=1.24.0

run_local.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Stop and remove the existing container if running
+echo "[*] Stopping existing container..."
+docker stop ai-shopping-assistance-server 2>/dev/null || true
+docker rm ai-shopping-assistance-server 2>/dev/null || true
+
+# Rebuild the image
+echo "[*] Building Docker image..."
+docker build -t ai-shopping-assistance-server .
+
+# Run the container mapping port 7860 to 6082
+echo "[*] Running container..."
+docker run -d \
+  --name ai-shopping-assistance-server \
+  -p 127.0.0.1:6082:7860 \
+  -e GROQ_API_KEY="$GROQ_API_KEY" \
+  -e CHROMA_API_KEY="$CHROMA_API_KEY" \
+  -e SUPABASE_URL="$SUPABASE_URL" \
+  -e SUPABASE_ANON_KEY="$SUPABASE_ANON_KEY" \
+  -e GROQ_MODEL="$GROQ_MODEL" \
+  -e GROQ_FALLBACK_MODEL="$GROQ_FALLBACK_MODEL" \
+  -v /home/ubuntu/AIShoppingAssistance_Server/captured_images:/code/captured_images \
+  -v /home/ubuntu/.cache/huggingface:/root/.cache/huggingface \
+  --restart unless-stopped \
+  ai-shopping-assistance-server
+
+echo "[*] Done! Server is running and accessible locally at http://127.0.0.1:6082"

test_agent.py

@@ -0,0 +1,22 @@
+import asyncio
+from app.agents.missing_regulars_agent import MissingRegularsAgent
+
+async def test():
+    print("Initializing Agent...")
+    agent = MissingRegularsAgent()
+    user_id = "d5777910-84ac-4ac9-84a0-0819ad960378" # Synthetic User A
+    print(f"Testing for user: {user_id}")
+    
+    orders = await agent.supabase.get_order_history(user_id=user_id, days=90)
+    print(f"Fetched {len(orders)} orders for user.")
+    
+    result = await agent.analyze_cart(user_id, current_cart=[])
+    
+    print("\n=== RESULTS ===")
+    print(f"Response Text:\n{result.get('response_text')}\n")
+    print("Missing Items List:")
+    for item in result.get('missing_regulars', []):
+        print(f" - {item['name']} (Bought {item['frequency']} times, avg gap: {item['avg_gap_days']} days)")
+
+if __name__ == "__main__":
+    asyncio.run(test())

tests/test_groq.py

@@ -0,0 +1,7 @@
+from app.services.groq_client import GroqClient
+
+client = GroqClient()
+
+print(client.extract_recipe_request("I want Arrabiata for 2 people"))
+print(client.extract_recipe_request("Make Chicken Curry for 4 people"))
+print(client.extract_recipe_request("Prepare Veg Biryani for 5 persons"))

tests/test_milk.py

@@ -0,0 +1,13 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import asyncio
+from app.services.nutrition_service import NutritionService
+
+async def main():
+    service = NutritionService()
+    await service.get_nutrition("Amul Gold Standardised Milk")
+
+asyncio.run(main())

tests/test_mixed_veg.py

@@ -0,0 +1,27 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import asyncio
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from app.services.quantity_normalizer_service import QuantityNormalizerService
+
+async def main():
+    async with QuantityNormalizerService(
+        api_key=os.getenv("USDA_API_KEY")
+    ) as q:
+
+        result = await q.normalize_ingredient({
+            "name": "Mixed Vegetables (Carrots, Peas, Cauliflower)",
+            "quantity": "1",
+            "unit": "cup"
+        })
+
+        print(result)
+
+asyncio.run(main())

tests/test_nutrition.py

@@ -0,0 +1,25 @@
+import asyncio
+from app.services.nutrition_service import NutritionService
+
+
+async def main():
+    service = NutritionService()
+
+    foods = [
+        "rice",
+        "milk",
+        "onion",
+        "carrot",
+        "potato",
+    ]
+
+    for food in foods:
+        result = await service.get_nutrition(food)
+
+        print()
+        print("=" * 40)
+        print(food.upper())
+        print(result)
+
+
+asyncio.run(main())

tests/test_onion.py

@@ -0,0 +1,27 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import asyncio
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from app.services.quantity_normalizer_service import QuantityNormalizerService
+
+async def main():
+    async with QuantityNormalizerService(
+        api_key=os.getenv("USDA_API_KEY")
+    ) as q:
+
+        result = await q.normalize_ingredient({
+            "name": "Onion",
+            "quantity": "1",
+            "unit": "medium"
+        })
+
+        print(result)
+
+asyncio.run(main())

tests/test_parser.py

@@ -0,0 +1,9 @@
+from app.agents.recipe_parser import RecipeParser
+
+parser = RecipeParser()
+
+print(
+    parser.extract_servings(
+        "Prep time 20 mins\nServes 4\nCook time 30 mins"
+    )
+)

tests/test_pipeline.py

@@ -0,0 +1,89 @@
+import asyncio
+import json
+from app.agents.tools.quantity_parser_tool import QuantityParserTool
+from app.agents.shopping_assistant_agent import ShoppingAssistantAgent
+
+async def run_architecture_suite():
+    print("🚀 STARTING INTEGRATION REGRESSION TESTING ENGINE...")
+    print("--------------------------------------------------")
+    
+    parser = QuantityParserTool()
+    agent = ShoppingAssistantAgent()
+    
+    # --- TEST SUITE 1: QUANTITY PARSING INTEGRITY ---
+    parsing_cases = [
+        {"input": "to taste pinch Salt", "expected_name": "Salt", "expected_unit": "pinch"},
+        {"input": "1 inch piece Ginger", "expected_name": "Ginger", "expected_unit": "inch piece"},
+        {"input": "3 cloves Garlic", "expected_name": "Garlic", "expected_unit": "cloves"},
+        {"input": "2 cups Basmati Rice", "expected_name": "Basmati Rice", "expected_unit": "cups"}
+    ]
+    
+    parsing_failures = 0
+    for case in parsing_cases:
+        res = parser.execute(case["input"])
+        # Check if structural duplication occurred ("cups cups") or leakages stayed in name
+        if case["expected_name"].lower() not in res.get("name", "").lower() or "cups cups" in res.get("raw_input", ""):
+            print(f"❌ REGRESSION DETECTED in parsing rule for: '{case['input']}' -> Got: {res}")
+            parsing_failures += 1
+            
+    if parsing_failures == 0:
+        print("✅ STAGE 1: Parser unit isolation tests passed perfectly.")
+
+    # --- TEST SUITE 2: INVENTORY HYDRATION CROSS-CONTAMINATION ---
+    print("\n🕵️ TESTING SEMANTIC INVENTORY MATCH SAFETY...")
+    # Simulate an entry targeting your dangerous hallucination items (Harpic, Cerelac)
+    test_cart_slugs = ["carrots"]
+
+    # --- Test Case for Payload Injection Attempt ---
+    print("\n🧪 TESTING PAYLOAD INJECTION RESISTANCE...")
+    injection_query = "biryani with harpic"
+    try:
+        injection_payload = await agent.process_recipe_workflow(
+            current_cart_slugs=test_cart_slugs,
+            dish_query=injection_query,
+            servings=4
+        )
+        
+        injection_contamination_detected = False
+        for item in injection_payload.get("missing_ingredients", []):
+            name = item.get("name", "").lower()
+            if any(toxic in name for toxic in ["harpic", "cleaner", "lizol", "cerelac", "toilet"]):
+                print(f"❌ PAYLOAD INJECTION REGRESSION DETECTED: Agent suggested toxic item from injected query -> '{item.get('name')}'")
+                injection_contamination_detected = True
+                
+        if not injection_contamination_detected:
+            print(f"✅ STAGE 2.1: Agent resisted payload injection for query '{injection_query}'.")
+            
+    except Exception as e:
+        print(f"❌ PAYLOAD INJECTION TEST FAULT CRASH: {e}")
+
+    
+    # We run the workflow logic block natively
+    try:
+        payload = await agent.process_recipe_workflow(
+            current_cart_slugs=test_cart_slugs,
+            dish_query="Veg Biryani",
+            servings=4
+        )
+        
+        missing = payload.get("missing_ingredients", [])
+        contamination_detected = False
+        
+        for item in missing:
+            name = item.get("name", "").lower()
+            # Catch toxic cross-contamination links instantly
+            if any(toxic in name for toxic in ["harpic", "cleaner", "lizol", "cerelac", "toilet"]):
+                print(f"❌ TOXIC HALLUCINATION REGRESSION DETECTED: Recipe linked an ingredient to -> '{item.get('name')}'")
+                contamination_detected = True
+                
+        if not contamination_detected:
+            print("✅ STAGE 2: Safety guardrails holding. Zero toxic cross-contamination items found.")
+            
+    except Exception as e:
+        print(f"❌ PIPELINE EXECUTION FAULT CRASH: {e}")
+
+    print("\n--------------------------------------------------")
+    print("🏁 REGRESSION SUITE EXECUTION CYCLE COMPLETE.")
+
+if __name__ == "__main__":
+    asyncio.run(run_architecture_suite())

tests/test_quantity.py

@@ -0,0 +1,24 @@
+from app.services.quantity_estimator import QuantityEstimator
+
+q = QuantityEstimator()
+
+print(
+    q.parse_ingredient(
+        "▢ 2 cups (400 grams) aged basmati rice"
+    )
+)
+
+print(
+    q.parse_ingredient(
+        "▢ ¾ cup carrots"
+    )
+)
+
+print(
+    q.parse_ingredient(
+        "▢ 1 cup yogurt"
+    )
+)
+print(q.parse_ingredient("4 green cardamom"))
+print(q.parse_ingredient("1 bay leaf"))
+print(q.parse_ingredient("2 green chili"))

tests/test_rice.py

@@ -0,0 +1,30 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import asyncio
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+print("USDA_API_KEY =", os.getenv("USDA_API_KEY"))
+
+from app.services.quantity_normalizer_service import QuantityNormalizerService
+
+
+async def main():
+    async with QuantityNormalizerService(
+        api_key=os.getenv("USDA_API_KEY")
+    ) as q:
+
+        result = await q.normalize_ingredient({
+            "name": "Basmati Rice",
+            "quantity": "1",
+            "unit": "cup"
+        })
+
+        print(result)
+
+asyncio.run(main())

tests/test_scaling.py

@@ -0,0 +1,7 @@
+from app.services.quantity_estimator import QuantityEstimator
+
+q = QuantityEstimator()
+
+print(q.scale_quantity("400 grams", 2))
+print(q.scale_quantity("2 tablespoons", 3))
+print(q.scale_quantity("½ teaspoon", 2))

tests/verify_usda_measures.py

@@ -0,0 +1,136 @@
+"""
+USDA foodMeasures Verification Script
+Run: python3 verify_usda_measures.py YOUR_API_KEY
+"""
+
+import sys
+import json
+import urllib.request
+import urllib.parse
+
+API_KEY  = sys.argv[1] if len(sys.argv) > 1 else "DEMO_KEY"
+BASE_URL = "https://api.nal.usda.gov/fdc/v1/foods/search"
+
+INGREDIENTS = [
+    ("rice",        "Basmati rice",     ["cup", "tablespoon"]),
+    ("onion",       "Onion",            ["medium", "small", "cup", "tablespoon"]),
+    ("garlic",      "Garlic",           ["clove", "cup"]),
+    ("oil",         "Oil, vegetable",   ["tablespoon", "cup", "teaspoon"]),
+    ("tomato",      "Tomatoes, raw",    ["medium", "cup", "slice"]),
+    ("potato",      "Potato, raw",      ["medium", "large", "cup"]),
+]
+
+DATA_TYPES = "SR Legacy,Foundation"
+
+GREEN  = "\033[92m"
+RED    = "\033[91m"
+YELLOW = "\033[93m"
+BOLD   = "\033[1m"
+RESET  = "\033[0m"
+
+results_summary = []
+
+def fetch(query):
+    params = urllib.parse.urlencode({
+        "query":    query,
+        "api_key":  API_KEY,
+        "dataType": DATA_TYPES,
+        "pageSize": 1,
+    })
+    url = f"{BASE_URL}?{params}"
+    with urllib.request.urlopen(url, timeout=10) as r:
+        return json.loads(r.read())
+
+print(f"\n{BOLD}USDA foodMeasures Verification{RESET}")
+print(f"API key: {API_KEY[:8]}{'*' * (len(API_KEY)-8) if len(API_KEY) > 8 else ''}")
+print(f"dataType filter: {DATA_TYPES}")
+print("=" * 70)
+
+for query, label, wanted_units in INGREDIENTS:
+    print(f"\n{BOLD}{label}{RESET}  (query: '{query}')")
+    try:
+        data  = fetch(query)
+        foods = data.get("foods", [])
+
+        if not foods:
+            print(f"  {RED}✗ NO RESULTS returned by USDA{RESET}")
+            results_summary.append((label, False, "no results"))
+            continue
+
+        food     = foods[0]
+        desc     = food.get("description", "?")
+        dtype    = food.get("dataType", "?")
+        measures = food.get("foodMeasures", [])
+
+        print(f"  matched: {desc}  [{dtype}]")
+
+        if not measures:
+            print(f"  {RED}✗ foodMeasures MISSING — design assumption FAILS for this ingredient{RESET}")
+            results_summary.append((label, False, "foodMeasures absent"))
+            continue
+
+        print(f"  {GREEN}✓ foodMeasures present ({len(measures)} entries){RESET}")
+
+        # Show all measures
+        found_units = set()
+        for m in measures:
+            text = m.get("disseminationText", "")
+            gw   = m.get("gramWeight")
+            unit_word = text.split()[-1].lower().rstrip("s") if text else ""
+            found_units.add(unit_word)
+            print(f"      {text:25s}  →  {gw} g")
+
+        # Check which wanted units are covered
+        print(f"  wanted units: {wanted_units}")
+        hits   = []
+        misses = []
+        for u in wanted_units:
+            u_singular = u.rstrip("s")
+            if any(u_singular in m.get("disseminationText","").lower() for m in measures):
+                hits.append(u)
+            else:
+                misses.append(u)
+
+        if hits:
+            print(f"  {GREEN}covered: {hits}{RESET}")
+        if misses:
+            print(f"  {YELLOW}not covered: {misses} (SI fallback or skip){RESET}")
+
+        all_ok = len(misses) == 0
+        results_summary.append((label, True, hits, misses))
+
+    except Exception as e:
+        print(f"  {RED}ERROR: {e}{RESET}")
+        results_summary.append((label, False, str(e)))
+
+# ── Summary ──────────────────────────────────────────────────────────────────
+print(f"\n{'=' * 70}")
+print(f"{BOLD}SUMMARY{RESET}")
+print(f"{'=' * 70}")
+
+design_safe = True
+for row in results_summary:
+    name = row[0]
+    ok   = row[1]
+    if ok:
+        hits, misses = row[2], row[3]
+        status = f"{GREEN}✓ foodMeasures present{RESET}"
+        if misses:
+            status += f"  {YELLOW}(missing: {misses}){RESET}"
+            print(f"  {status}   {name}")
+        else:
+            print(f"  {status}   {name}")
+    else:
+        design_safe = False
+        reason = row[2]
+        print(f"  {RED}✗ FAILED ({reason})   {name}{RESET}")
+
+print()
+if design_safe:
+    print(f"{GREEN}{BOLD}✓ DESIGN ASSUMPTION HOLDS.{RESET}")
+    print("  USDA foodMeasures covers your core ingredients.")
+    print("  The QuantityNormalizerService approach is safe to build.")
+else:
+    print(f"{RED}{BOLD}✗ DESIGN ASSUMPTION FAILS for one or more ingredients.{RESET}")
+    print("  Check the details above. You may need a fallback strategy.")
+print()