Merge branch async-generation-catalogue: async iterative generation + supplier catalogue

main.py

@@ -6,6 +6,8 @@ import time
 import json
 import traceback
 import wave
+import threading
+import concurrent.futures
 from datetime import datetime, timedelta
 
 from flask import Flask, request, jsonify, Response
@@ -87,9 +89,15 @@ except Exception as e:
 #
 # All changes are backwards-compatible – the client contract is unchanged.
 # ---------------------------------------------------------------------------
-CATEGORY_MODEL   = "gemini-3.1-flash-lite"          # was gemini-2.5-flash
-GENERATION_MODEL = "gemini-3.1-flash-image-preview"  # Nano Banana 2 (was gemini-2.0-flash-exp-image-generation)
-SUMMARY_MODEL    = "gemini-3.1-flash-lite"           # was gemini-2.0-flash-lite
+CATEGORY_MODEL   = os.environ.get("CATEGORY_MODEL",   "gemini-3.1-flash-lite")          # was gemini-2.5-flash
+GENERATION_MODEL = os.environ.get("GENERATION_MODEL",  "gemini-3.1-flash-image-preview") # Nano Banana 2 (was gemini-2.0-flash-exp-image-generation)
+SUMMARY_MODEL    = os.environ.get("SUMMARY_MODEL",     "gemini-3.1-flash-lite")          # was gemini-2.0-flash-lite
+
+# Step-guide generation (async iterative pipeline)
+PLAN_TEXT_MODEL      = os.environ.get("PLAN_TEXT_MODEL", "gemini-3.1-flash-lite")   # fast text-only planning call
+FALLBACK_IMAGE_MODEL = os.environ.get("FALLBACK_IMAGE_MODEL", "gemini-2.5-flash-image")  # nano banana original
+IMAGE_CALL_TIMEOUT_S = float(os.environ.get("IMAGE_CALL_TIMEOUT_S", "28"))           # per step-image call
+GENERATION_STALE_S   = float(os.environ.get("GENERATION_STALE_S", "240"))            # progress heartbeat staleness
 
 # --- Stripe Initialization ---
 STRIPE_SECRET_KEY    = os.environ.get("STRIPE_SECRET_KEY")
@@ -168,6 +176,63 @@ def parse_numbered_steps(text):
     steps_found = re.findall(r"\n\s*(\d+)\.\s*(.*)", text, re.MULTILINE)
     return [{"stepNumber": int(num), "text": desc.strip()} for num, desc in steps_found]
 
+def _update_progress(project_id, **fields):
+    """Writes generation progress fields under the project so the client can poll real state."""
+    fields['updatedAt'] = datetime.utcnow().isoformat()
+    db_ref.child(f'projects/{project_id}/generationProgress').update(fields)
+
+_TOOL_STOPWORDS = {'a', 'an', 'the', 'of', 'for', 'and', 'or', 'with', 'to', 'in', 'on', 'set', 'pair', 'piece', 'pieces', 'small', 'large', 'medium', 'new', 'some', 'optional'}
+
+SUPPORTED_CITIES = ['Harare', 'Bulawayo', 'Gweru', 'Mutare', 'Other']
+
+def _normalize_tool_name(name):
+    """Lowercase, strip punctuation/stopwords, singularize trailing 's' for catalogue matching."""
+    words = re.sub(r"[^a-z0-9\s]", " ", (name or "").lower()).split()
+    normalized = []
+    for w in words:
+        if w in _TOOL_STOPWORDS:
+            continue
+        if len(w) > 3 and w.endswith('s') and not w.endswith('ss'):
+            w = w[:-1]
+        normalized.append(w)
+    return " ".join(normalized)
+
+def match_tools_to_catalogue(tools_list):
+    """Matches free-text tool names against the supplier catalogue by keyword-token overlap.
+
+    Returns one best match per tool (score >= 1), cheap enough to run inline for ~1-2k items.
+    """
+    catalogue = db_ref.child('catalogue').get() or {}
+    matches = []
+    for tool in tools_list:
+        tool_tokens = set(_normalize_tool_name(tool).split())
+        if not tool_tokens:
+            continue
+        best_item, best_score = None, 0
+        for item_id, item in catalogue.items():
+            if not isinstance(item, dict) or not item.get('inStock', True):
+                continue
+            keywords = set(item.get('keywords', []))
+            score = len(tool_tokens & keywords)
+            normalized_name = item.get('normalizedName', '')
+            if normalized_name and set(normalized_name.split()) <= tool_tokens:
+                score += 2
+            if score > best_score:
+                best_item, best_score = (item_id, item), score
+        if best_item and best_score >= 1:
+            item_id, item = best_item
+            matches.append({
+                'tool':     tool,
+                'itemId':   item_id,
+                'name':     item.get('name', ''),
+                'price':    item.get('price', 0),
+                'currency': item.get('currency', 'USD'),
+                'supplier': item.get('supplier', 'Electrosales'),
+                'city':     item.get('city', 'Harare'),
+                'imageUrl': item.get('imageUrl', ''),
+            })
+    return matches
+
 def _convert_pcm_to_wav(pcm_data, sample_rate=24000, channels=1, sample_width=2):
     """Wraps raw PCM audio data in a WAV container in memory."""
     audio_buffer = io.BytesIO()
@@ -994,6 +1059,260 @@ def admin_send_email():
 # 7. DIY PROJECT ENDPOINTS (Core Logic)
 # -----------------------------------------------------------------------------
 
+# -----------------------------------------------------------------------------
+# SUPPLIER CATALOGUE (ADMIN) — grounds the tools & supplies list in real products
+# -----------------------------------------------------------------------------
+
+def _build_catalogue_item(data, admin_uid):
+    """Validates admin input and computes the matching fields; returns None when invalid."""
+    name = (data.get('name') or '').strip()
+    try:
+        price = round(float(data.get('price')), 2)
+    except (TypeError, ValueError):
+        price = None
+    if not name or price is None or price < 0:
+        return None
+
+    normalized = _normalize_tool_name(name)
+    tokens = set(normalized.split())
+    for extra in data.get('keywords') or []:
+        if isinstance(extra, str):
+            tokens |= set(_normalize_tool_name(extra).split())
+
+    return {
+        'name':           name,
+        'normalizedName': normalized,
+        'keywords':       sorted(tokens),
+        'price':          price,
+        'currency':       (data.get('currency') or 'USD').upper(),
+        'supplier':       (data.get('supplier') or 'Electrosales').strip(),
+        'city':           data.get('city') if data.get('city') in SUPPORTED_CITIES else 'Harare',
+        'category':       (data.get('category') or 'General').strip(),
+        'imageUrl':       data.get('imageUrl') or '',
+        'inStock':        bool(data.get('inStock', True)),
+        'createdAt':      datetime.utcnow().isoformat(),
+        'createdBy':      admin_uid,
+    }
+
+
+@app.route('/api/admin/catalogue', methods=['GET'])
+def admin_list_catalogue():
+    try:
+        verify_admin(request.headers.get('Authorization'))
+    except PermissionError as e:
+        return jsonify({'error': str(e)}), 403
+    items = db_ref.child('catalogue').get() or {}
+    result = [{'itemId': key, **item} for key, item in items.items() if isinstance(item, dict)]
+    result.sort(key=lambda x: x.get('createdAt', ''), reverse=True)
+    return jsonify({'items': result})
+
+
+@app.route('/api/admin/catalogue', methods=['POST'])
+def admin_create_catalogue_item():
+    try:
+        admin_uid = verify_admin(request.headers.get('Authorization'))
+    except PermissionError as e:
+        return jsonify({'error': str(e)}), 403
+    item = _build_catalogue_item(request.get_json(silent=True) or {}, admin_uid)
+    if not item:
+        return jsonify({'error': 'A valid name and non-negative price are required.'}), 400
+    ref = db_ref.child('catalogue').push(item)
+    return jsonify({'itemId': ref.key, **item}), 201
+
+
+@app.route('/api/admin/catalogue/bulk', methods=['POST'])
+def admin_bulk_create_catalogue():
+    """Confirm-save for the extract flow: saves the reviewed items in one call."""
+    try:
+        admin_uid = verify_admin(request.headers.get('Authorization'))
+    except PermissionError as e:
+        return jsonify({'error': str(e)}), 403
+    raw_items = (request.get_json(silent=True) or {}).get('items')
+    if not isinstance(raw_items, list) or not raw_items:
+        return jsonify({'error': 'items must be a non-empty array.'}), 400
+
+    created, skipped = [], 0
+    for raw in raw_items:
+        item = _build_catalogue_item(raw if isinstance(raw, dict) else {}, admin_uid)
+        if not item:
+            skipped += 1
+            continue
+        ref = db_ref.child('catalogue').push(item)
+        created.append({'itemId': ref.key, **item})
+    return jsonify({'created': created, 'createdCount': len(created), 'skippedCount': skipped}), 201
+
+
+@app.route('/api/admin/catalogue/extract', methods=['POST'])
+def admin_extract_catalogue():
+    """AI-extracts products from an uploaded catalogue image or PDF. Nothing is saved —
+    the parsed items go back to the admin for review, then /bulk persists them."""
+    try:
+        verify_admin(request.headers.get('Authorization'))
+    except PermissionError as e:
+        return jsonify({'error': str(e)}), 403
+
+    if 'file' not in request.files:
+        return jsonify({'error': 'A catalogue file (image or PDF) is required.'}), 400
+    upload = request.files['file']
+    file_bytes = upload.read()
+    if len(file_bytes) > 10 * 1024 * 1024:
+        return jsonify({'error': 'File too large (max 10 MB).'}), 400
+
+    extract_prompt = (
+        "Extract every product from this supplier catalogue / price list. "
+        "Return a JSON array where each element is: "
+        '{"name": string, "price": number (numeric only, no currency symbols; 0 if missing), '
+        '"category": string (e.g. Electrical, Hand Tools, Fasteners, Paint, Plumbing, General), '
+        '"inStock": boolean (true unless clearly marked out of stock)}. '
+        "Skip headings, page numbers and non-product rows."
+    )
+
+    is_pdf = upload.mimetype == 'application/pdf' or (upload.filename or '').lower().endswith('.pdf')
+    try:
+        if is_pdf:
+            contents = [extract_prompt, types.Part.from_bytes(data=file_bytes, mime_type='application/pdf')]
+        else:
+            contents = [extract_prompt, Image.open(io.BytesIO(file_bytes))]
+
+        resp = client.models.generate_content(
+            model=CATEGORY_MODEL,
+            contents=contents,
+            config=types.GenerateContentConfig(response_mime_type='application/json'),
+        )
+        raw_json = "".join(part.text or '' for part in resp.candidates[0].content.parts)
+        parsed = json.loads(raw_json)
+    except json.JSONDecodeError:
+        logger.error(f"[CATALOGUE EXTRACT] Model returned non-JSON output")
+        return jsonify({'error': 'Could not read products from this file. Try a clearer photo or a PDF.'}), 422
+    except Exception as e:
+        logger.error(f"[CATALOGUE EXTRACT] Extraction failed: {e}")
+        return jsonify({'error': f'Extraction failed: {str(e)}'}), 500
+
+    items = []
+    for entry in parsed if isinstance(parsed, list) else []:
+        if not isinstance(entry, dict) or not (entry.get('name') or '').strip():
+            continue
+        try:
+            price = round(float(entry.get('price', 0)), 2)
+        except (TypeError, ValueError):
+            price = 0
+        items.append({
+            'name':     entry['name'].strip(),
+            'price':    max(price, 0),
+            'category': (entry.get('category') or 'General').strip(),
+            'inStock':  bool(entry.get('inStock', True)),
+        })
+    return jsonify({'items': items})
+
+
+@app.route('/api/admin/catalogue/<string:item_id>', methods=['PUT'])
+def admin_update_catalogue_item(item_id):
+    try:
+        verify_admin(request.headers.get('Authorization'))
+    except PermissionError as e:
+        return jsonify({'error': str(e)}), 403
+    item_ref = db_ref.child(f'catalogue/{item_id}')
+    existing = item_ref.get()
+    if not existing:
+        return jsonify({'error': 'Catalogue item not found'}), 404
+
+    data = request.get_json(silent=True) or {}
+    updates = {}
+    if 'name' in data:
+        name = (data.get('name') or '').strip()
+        if not name:
+            return jsonify({'error': 'name cannot be empty'}), 400
+        normalized = _normalize_tool_name(name)
+        updates.update({'name': name, 'normalizedName': normalized, 'keywords': sorted(set(normalized.split()))})
+    if 'price' in data:
+        try:
+            price = round(float(data.get('price')), 2)
+        except (TypeError, ValueError):
+            return jsonify({'error': 'price must be a number'}), 400
+        if price < 0:
+            return jsonify({'error': 'price cannot be negative'}), 400
+        updates['price'] = price
+    for field in ('currency', 'supplier', 'category'):
+        if field in data and isinstance(data[field], str) and data[field].strip():
+            updates[field] = data[field].strip()
+    if 'city' in data:
+        if data['city'] not in SUPPORTED_CITIES:
+            return jsonify({'error': f'city must be one of: {", ".join(SUPPORTED_CITIES)}'}), 400
+        updates['city'] = data['city']
+    if 'inStock' in data:
+        updates['inStock'] = bool(data['inStock'])
+    if not updates:
+        return jsonify({'error': 'No valid fields to update.'}), 400
+
+    item_ref.update(updates)
+    return jsonify({'itemId': item_id, **existing, **updates})
+
+
+@app.route('/api/admin/catalogue/<string:item_id>', methods=['DELETE'])
+def admin_delete_catalogue_item(item_id):
+    try:
+        verify_admin(request.headers.get('Authorization'))
+    except PermissionError as e:
+        return jsonify({'error': str(e)}), 403
+    item_ref = db_ref.child(f'catalogue/{item_id}')
+    existing = item_ref.get()
+    if not existing:
+        return jsonify({'error': 'Catalogue item not found'}), 404
+    if existing.get('imageUrl'):
+        try:
+            bucket.blob(f'catalogue/{item_id}/image.jpg').delete()
+        except Exception as e:
+            logger.warning(f"[CATALOGUE] Could not delete image blob for {item_id}: {e}")
+    item_ref.delete()
+    return jsonify({'success': True})
+
+
+@app.route('/api/admin/catalogue/<string:item_id>/image', methods=['POST'])
+def admin_upload_catalogue_image(item_id):
+    try:
+        verify_admin(request.headers.get('Authorization'))
+    except PermissionError as e:
+        return jsonify({'error': str(e)}), 403
+    item_ref = db_ref.child(f'catalogue/{item_id}')
+    if not item_ref.get():
+        return jsonify({'error': 'Catalogue item not found'}), 404
+    if 'image' not in request.files:
+        return jsonify({'error': 'An image file is required.'}), 400
+    image_file = request.files['image']
+    try:
+        # Normalize to JPEG so the stored blob path/type is predictable
+        pil_img = Image.open(io.BytesIO(image_file.read())).convert('RGB')
+        buf = io.BytesIO()
+        pil_img.save(buf, format='JPEG', optimize=True, quality=80)
+        image_url = upload_to_storage(buf.getvalue(), f'catalogue/{item_id}/image.jpg', 'image/jpeg')
+    except Exception as e:
+        logger.error(f"[CATALOGUE] Image upload failed for {item_id}: {e}")
+        return jsonify({'error': 'Failed to process or upload the image.'}), 500
+    item_ref.update({'imageUrl': image_url})
+    return jsonify({'itemId': item_id, 'imageUrl': image_url})
+
+
+@app.route('/api/projects/<string:project_id>/tool-matches', methods=['GET'])
+def get_project_tool_matches(project_id):
+    """Returns cached catalogue matches for the project's tools, computing them on demand
+    for projects generated before the catalogue existed."""
+    uid = verify_token(request.headers.get('Authorization'))
+    if not uid:
+        return jsonify({'error': 'Unauthorized'}), 401
+    project = db_ref.child(f'projects/{project_id}').get()
+    if not project or project.get('uid') != uid:
+        return jsonify({'error': 'Project not found or access denied'}), 404
+
+    matches = project.get('toolMatches')
+    if matches is None:
+        matches = match_tools_to_catalogue(project.get('toolsList') or [])
+        db_ref.child(f'projects/{project_id}').update({
+            'toolMatches':          matches,
+            'toolMatchesUpdatedAt': datetime.utcnow().isoformat(),
+        })
+    return jsonify({'matches': matches})
+
+
 @app.route('/api/projects', methods=['POST'])
 def create_project():
     uid = verify_token(request.headers.get('Authorization'))
@@ -1078,282 +1397,285 @@ def create_project():
         return jsonify({'error': f"An error occurred: {e}"}), 500
 
 
-@app.route('/api/projects/<string:project_id>/approve', methods=['PUT'])
-def approve_project_plan(project_id):
-    start_time = time.time()
-    logger.info(f"[PROJECT APPROVAL] Starting approval process for project: {project_id}")
+def _progress_is_stale(progress):
+    """True when a 'generating' project's heartbeat is older than GENERATION_STALE_S (e.g. server restarted mid-job)."""
+    updated_at = (progress or {}).get('updatedAt')
+    if not updated_at:
+        return True
+    try:
+        last = datetime.fromisoformat(updated_at)
+    except ValueError:
+        return True
+    return (datetime.utcnow() - last).total_seconds() > GENERATION_STALE_S
 
-    uid = verify_token(request.headers.get('Authorization'))
-    if not uid:
-        return jsonify({'error': 'Unauthorized'}), 401
 
-    user_ref  = db_ref.child(f'users/{uid}')
-    user_data = user_ref.get()
-    if not user_data or user_data.get('credits', 0) < 5:
-        return jsonify({'error': 'Insufficient credits'}), 402
+def _call_with_timeout(fn, timeout_s, *args, **kwargs):
+    """Runs fn in a worker thread; raises concurrent.futures.TimeoutError past timeout_s.
 
-    project_ref  = db_ref.child(f'projects/{project_id}')
-    project_data = project_ref.get()
-    if not project_data or project_data.get('uid') != uid:
-        return jsonify({'error': 'Project not found or access denied'}), 404
+    shutdown(wait=False) so a hung API call can't block the generation loop.
+    """
+    pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+    try:
+        return pool.submit(fn, *args, **kwargs).result(timeout=timeout_s)
+    finally:
+        pool.shutdown(wait=False)
 
-    selected_option = request.json.get('selectedOption')
-    logger.info(f"[PROJECT APPROVAL] Selected option: {selected_option}")
 
-    # Image download and processing timing
-    image_download_start = time.time()
-    try:
-        response = requests.get(project_data['userImageURL'], timeout=30)
-        response.raise_for_status()
-    except requests.RequestException as e:
-        logger.error(f"[PROJECT APPROVAL] ERROR: Image download failed: {e}")
-        return jsonify({'error': 'Failed to download project image'}), 500
+def _request_step_image(chat, prompt_parts):
+    """Sends one chat turn that must yield exactly one inline image."""
+    resp = chat.send_message(prompt_parts)
+    for part in resp.candidates[0].content.parts:
+        if part.inline_data is not None:
+            return Image.open(io.BytesIO(part.inline_data.data)).convert('RGB')
+    raise ValueError('Model returned no image for this step')
 
-    image_download_time = time.time() - image_download_start
-    logger.info(f"[PROJECT APPROVAL] Image download completed in {image_download_time:.3f}s, size: {len(response.content)} bytes")
 
-    image_processing_start = time.time()
-    try:
-        pil_image = Image.open(io.BytesIO(response.content)).convert('RGB')
-    except Exception as e:
-        logger.error(f"[PROJECT APPROVAL] ERROR: Image processing failed: {e}")
-        return jsonify({'error': 'Failed to process project image'}), 500
-
-    image_processing_time = time.time() - image_processing_start
-    logger.info(f"[PROJECT APPROVAL] Image processing completed in {image_processing_time:.3f}s")
-
-    # Context preparation timing
-    context_start = time.time()
-    context = (
-        f"The user chose the upcycling project: '{selected_option}'."
-        if selected_option
-        else f"The user has approved the plan for '{project_data['projectTitle']}'."
-    )
+def _run_guide_generation(uid, project_id, selected_option):
+    """Background job: text plan -> one image per chat turn (iterative refinement) -> upload/TTS -> finalize.
 
-    detailed_prompt = f"""
-    You are a DIY expert. The user wants to proceed with the project titled "{project_data['projectTitle']}".
-    {context}
-    Provide a detailed guide. For each step, you MUST provide a simple, clear illustrative image.
-    Format your response EXACTLY like this:
-    TOOLS AND MATERIALS:
-    - Tool A
-    - Material B
-    STEPS(Maximum 5 steps):
-    1. First step instructions.
-    2. Second step instructions...
+    Progress is written to projects/{id}/generationProgress after every phase so the
+    client can poll real state. Credits are deducted only on success; any failure
+    flips the project to 'generation_failed' so the client can offer a retry.
     """
-    context_time = time.time() - context_start
-    logger.info(f"[PROJECT APPROVAL] Context preparation completed in {context_time:.3f}s")
-
+    start_time = time.time()
+    project_ref = db_ref.child(f'projects/{project_id}')
+    user_ref = db_ref.child(f'users/{uid}')
     try:
-        # AI generation timing
-        ai_start = time.time()
-        logger.info(f"[PROJECT APPROVAL] Starting AI generation with model: {GENERATION_MODEL}")
+        project_data = project_ref.get()
 
-        chat = client.chats.create(
-            model=GENERATION_MODEL,
-            config=types.GenerateContentConfig(response_modalities=["Text", "Image"])
+        response = requests.get(project_data['userImageURL'], timeout=30)
+        response.raise_for_status()
+        pil_image = Image.open(io.BytesIO(response.content)).convert('RGB')
+
+        context = (
+            f"The user chose the upcycling project: '{selected_option}'."
+            if selected_option
+            else f"The user has approved the plan for '{project_data['projectTitle']}'."
         )
-        full_resp = chat.send_message([detailed_prompt, pil_image])
-        ai_time = time.time() - ai_start
-        logger.info(f"[PROJECT APPROVAL] AI generation completed in {ai_time:.3f}s")
-
-        # Response parsing timing
-        parsing_start = time.time()
-        gen_parts = full_resp.candidates[0].content.parts
-
-        combined_text = ""
-        inline_images = []
-        for part in gen_parts:
-            if part.text is not None:
-                combined_text += part.text + "\n"
-            if part.inline_data is not None:
-                img = Image.open(io.BytesIO(part.inline_data.data)).convert('RGB')
-                inline_images.append(img)
-
-        combined_text = combined_text.strip()
-        parsing_time = time.time() - parsing_start
-        logger.info(f"[PROJECT APPROVAL] Response parsing completed in {parsing_time:.3f}s, found {len(inline_images)} images")
-
-        # Text extraction timing with robust error handling
-        extraction_start = time.time()
-
-        logger.info(f"[PROJECT APPROVAL] AI Response structure check:")
-        logger.info(f"[PROJECT APPROVAL] Full response length: {len(combined_text)}")
-        logger.info(f"[PROJECT APPROVAL] Contains 'TOOLS AND MATERIALS': {'TOOLS AND MATERIALS' in combined_text.upper()}")
-        logger.info(f"[PROJECT APPROVAL] Contains 'STEPS': {'STEPS' in combined_text.upper()}")
-        logger.info(f"[PROJECT APPROVAL] Response preview: {combined_text[:300]}...")
+
+        # --- Phase A: text-only plan on a fast model (guarantees 5 parseable steps) ---
+        _update_progress(project_id, phase='planning', message='Planning your step-by-step guide...')
+
+        plan_prompt = f"""
+        You are a DIY expert. The user wants to proceed with the project titled "{project_data['projectTitle']}".
+        {context}
+        Provide a detailed guide with EXACTLY 5 steps. Do not include any images.
+        Format your response EXACTLY like this:
+        TOOLS AND MATERIALS:
+        - Tool A
+        - Material B
+        STEPS(Maximum 5 steps):
+        1. First step instructions.
+        2. Second step instructions...
+        """
+        plan_resp = client.models.generate_content(model=PLAN_TEXT_MODEL, contents=[plan_prompt, pil_image])
+        combined_text = "".join(part.text or "" for part in plan_resp.candidates[0].content.parts).strip()
+        logger.info(f"[GUIDE GEN] Plan text generated in {time.time() - start_time:.1f}s, length {len(combined_text)}")
 
         tools_match = re.search(r"TOOLS AND MATERIALS:\s*(.*?)\s*(?=STEPS\s*\(|STEPS\s*:|$)", combined_text, re.DOTALL | re.IGNORECASE)
         steps_match = re.search(r"STEPS\s*\([^)]*\):\s*(.*)|STEPS\s*:\s*(.*)", combined_text, re.DOTALL | re.IGNORECASE)
+        if not tools_match or not steps_match:
+            logger.error(f"[GUIDE GEN] Could not parse plan. Full text: {combined_text}")
+            raise ValueError('AI response format error: could not parse the plan')
 
-        if not tools_match:
-            logger.error(f"[PROJECT APPROVAL] ERROR: Could not find TOOLS AND MATERIALS section in AI response")
-            logger.error(f"[PROJECT APPROVAL] AI Response full text: {combined_text}")
-            return jsonify({'error': 'AI response format error: Could not parse tools section'}), 500
+        tools_section = tools_match.group(1).strip()
+        steps_section = (steps_match.group(1) or steps_match.group(2) or '').strip()
 
-        if not steps_match:
-            logger.error(f"[PROJECT APPROVAL] ERROR: Could not find STEPS section in AI response")
-            logger.error(f"[PROJECT APPROVAL] AI Response full text: {combined_text}")
-            return jsonify({'error': 'AI response format error: Could not parse steps section'}), 500
+        tools_list = [line.strip('- ').strip() for line in tools_section.split('\n') if line.strip()]
+        seen = set()
+        tools_list = [x for x in tools_list if x and not (x in seen or seen.add(x))]
 
-        tools_section = tools_match.group(1).strip()
-        steps_section = (steps_match.group(1) or steps_match.group(2)).strip() if steps_match else ""
+        parsed_steps = parse_numbered_steps(steps_section)[:5]
+        if len(parsed_steps) < 3 or not tools_list:
+            logger.error(f"[GUIDE GEN] Incomplete plan — steps: {len(parsed_steps)}, tools: {len(tools_list)}")
+            raise ValueError('AI plan was incomplete')
 
-        if not tools_section:
-            logger.error(f"[PROJECT APPROVAL] ERROR: Empty tools section found")
-            return jsonify({'error': 'AI response format error: Empty tools section'}), 500
+        total_steps = len(parsed_steps)
+        _update_progress(project_id, totalSteps=total_steps)
 
-        if not steps_section:
-            logger.error(f"[PROJECT APPROVAL] ERROR: Empty steps section found")
-            return jsonify({'error': 'AI response format error: Empty steps section'}), 500
+        # --- Phase B: iterative refinement — one illustrative image per chat turn ---
+        steps_block = '\n'.join(f"{s['stepNumber']}. {s['text']}" for s in parsed_steps)
 
-        tools_list = [line.strip("- ").strip() for line in tools_section.split('\n') if line.strip() and not line.strip().startswith('-')]
-        dash_tools = [line.strip("- ").strip() for line in tools_section.split('\n') if line.strip().startswith('-')]
-        tools_list.extend(dash_tools)
+        def _make_image_chat(model_name):
+            return client.chats.create(
+                model=model_name,
+                config=types.GenerateContentConfig(response_modalities=['Text', 'Image'])
+            )
 
-        # Remove duplicates while preserving order
-        seen = set()
-        tools_list = [x for x in tools_list if not (x in seen or seen.add(x))]
-
-        parsed_steps = parse_numbered_steps(steps_section)
-
-        if not tools_list:
-            logger.error(f"[PROJECT APPROVAL] ERROR: No tools parsed from response")
-            logger.error(f"[PROJECT APPROVAL] Tools section was: {tools_section}")
-            return jsonify({'error': 'AI response format error: No tools found'}), 500
-
-        if not parsed_steps:
-            logger.error(f"[PROJECT APPROVAL] ERROR: No steps parsed from response")
-            logger.error(f"[PROJECT APPROVAL] Steps section was: {steps_section}")
-            return jsonify({'error': 'AI response format error: No steps found'}), 500
-
-        extraction_time = time.time() - extraction_start
-        logger.info(f"[PROJECT APPROVAL] Text extraction completed in {extraction_time:.3f}s, tools: {len(tools_list)}, steps: {len(parsed_steps)}")
-
-        if len(parsed_steps) != len(inline_images):
-            logger.error(f"[PROJECT APPROVAL] ERROR: AI response mismatch - Steps: {len(parsed_steps)}, Images: {len(inline_images)}")
-            min_length = min(len(parsed_steps), len(inline_images))
-            if min_length > 0:
-                logger.info(f"[PROJECT APPROVAL] Attempting to proceed with {min_length} steps/images")
-                parsed_steps = parsed_steps[:min_length]
-                inline_images = inline_images[:min_length]
-            else:
-                return jsonify({'error': 'AI response mismatch: No valid steps and images found.'}), 500
-
-        # ---------------------------------------------------------------
-        # Step processing – image upload and TTS run IN PARALLEL per step
-        # using ThreadPoolExecutor so Nano Banana 2's longer generation
-        # time doesn't stack on top of Deepgram latency.
-        # ---------------------------------------------------------------
-        import concurrent.futures
-
-        step_processing_start = time.time()
-        final_steps = [None] * len(parsed_steps)
-        total_upload_time = 0
-        total_tts_time = 0
-
-        def process_single_step(args):
-            """Runs image upload and TTS concurrently for one step, returns completed step_info."""
-            i, step_info, pil_img = args
-            result = dict(step_info)  # shallow copy so we don't mutate shared state
-            img_url       = ""
-            narration_url = ""
+        upload_pool = concurrent.futures.ThreadPoolExecutor(max_workers=total_steps)
+
+        def _upload_and_tts(idx, step_info, step_img):
+            """Image upload (when present) and Deepgram TTS for one step; runs while later images generate."""
+            img_url = ''
+            if step_img is not None:
+                buf = io.BytesIO()
+                step_img.save(buf, format='JPEG', optimize=True, quality=70)
+                img_url = upload_to_storage(
+                    buf.getvalue(),
+                    f"users/{uid}/projects/{project_id}/steps/step_{idx+1}_image.jpg",
+                    'image/jpeg'
+                ) or ''
+            narration_url = generate_tts_audio_and_upload(step_info['text'], uid, project_id, idx + 1) or ''
+            return idx, {**step_info, 'imageUrl': img_url, 'narrationUrl': narration_url, 'isDone': False, 'notes': ''}
+
+        chat = None
+        needs_context = True
+        current_model = GENERATION_MODEL
+        fallback_used = False
+        upload_futures = []
+
+        for idx, step in enumerate(parsed_steps):
+            _update_progress(
+                project_id, phase='generating_images', currentStep=idx, model=current_model,
+                message=f"Illustrating step {idx + 1} of {total_steps}..."
+            )
+            step_img = None
+            attempts = 0
+            while step_img is None and attempts < 3:
+                attempts += 1
+                try:
+                    if chat is None:
+                        chat = _make_image_chat(current_model)
+                        needs_context = True
+                    if needs_context:
+                        prompt_parts = [(
+                            f'You are illustrating a DIY guide titled "{project_data["projectTitle"]}". The full plan is:\n'
+                            f"{steps_block}\n\n"
+                            "You will illustrate one step at a time. Keep the subject, style and lighting "
+                            "consistent with the attached photo of the user's item.\n"
+                            f"Generate ONLY the illustrative image for step {step['stepNumber']}: {step['text']}. "
+                            "Return exactly one image and no text."
+                        ), pil_image]
+                    else:
+                        prompt_parts = [
+                            f"Generate ONLY the illustrative image for step {step['stepNumber']}: {step['text']}. "
+                            "Return exactly one image and no text."
+                        ]
+                    ai_start = time.time()
+                    step_img = _call_with_timeout(_request_step_image, IMAGE_CALL_TIMEOUT_S, chat, prompt_parts)
+                    needs_context = False
+                    logger.info(f"[GUIDE GEN] Step {idx+1} image generated in {time.time() - ai_start:.1f}s on {current_model}")
+                except Exception as img_err:
+                    logger.warning(f"[GUIDE GEN] Step {idx+1} image attempt {attempts} failed on {current_model}: {img_err}")
+                    chat = None  # a timed-out/failed chat may be unusable; rebuild with context on retry
+                    if attempts >= 2 and not fallback_used:
+                        fallback_used = True
+                        current_model = FALLBACK_IMAGE_MODEL
+                        _update_progress(project_id, model=current_model,
+                                         message=f"Switching to backup image model for step {idx + 1}...")
+
+            # Keep the text step even if illustration failed — never truncate the guide.
+            if step_img is None:
+                logger.error(f"[GUIDE GEN] Step {idx+1} has no image after retries/fallback; keeping text-only step")
+            _update_progress(project_id, currentStep=idx + 1)
+            upload_futures.append(upload_pool.submit(_upload_and_tts, idx, step, step_img))
+
+        # --- Phase C: wait for the uploads/TTS that were fired as images arrived ---
+        _update_progress(project_id, phase='uploading', message='Uploading images and narrations...')
+        final_steps = [None] * total_steps
+        for future in concurrent.futures.as_completed(upload_futures):
+            idx, completed = future.result()
+            final_steps[idx] = completed
+        upload_pool.shutdown(wait=True)
+
+        # Ground tools in the supplier catalogue (best effort — never fails the guide)
+        tool_matches = []
+        try:
+            tool_matches = match_tools_to_catalogue(tools_list)
+        except Exception as match_err:
+            logger.warning(f"[GUIDE GEN] Catalogue matching failed: {match_err}")
+
+        project_ref.update({
+            'status':                'ready',
+            'toolsList':             tools_list,
+            'steps':                 final_steps,
+            'selectedOption':        selected_option or '',
+            'toolMatches':           tool_matches,
+            'toolMatchesUpdatedAt':  datetime.utcnow().isoformat(),
+        })
 
-            try:
-                # Encode JPEG in this thread before spawning sub-futures
-                img_byte_arr = io.BytesIO()
-                pil_img.save(img_byte_arr, format='JPEG', optimize=True, quality=70)
-                img_bytes_val = img_byte_arr.getvalue()
-                img_path      = f"users/{uid}/projects/{project_id}/steps/step_{i+1}_image.jpg"
+        current_credits = (user_ref.get() or {}).get('credits', 0)
+        user_ref.update({'credits': current_credits - 5})
 
-                # Fire image upload and TTS simultaneously
-                with concurrent.futures.ThreadPoolExecutor(max_workers=2) as inner_pool:
-                    img_upload_start = time.time()
-                    tts_start        = time.time()
+        _update_progress(project_id, status='ready', phase='done', currentStep=total_steps,
+                         message='Your guide is ready!', error='')
+        logger.info(f"[GUIDE GEN] SUCCESS project {project_id} in {time.time() - start_time:.1f}s "
+                    f"(steps: {total_steps}, fallback_used: {fallback_used})")
 
-                    img_future = inner_pool.submit(upload_to_storage, img_bytes_val, img_path, 'image/jpeg')
-                    tts_future = inner_pool.submit(generate_tts_audio_and_upload, result['text'], uid, project_id, i + 1)
+    except Exception as e:
+        logger.error(f"[GUIDE GEN] FAILED project {project_id} after {time.time() - start_time:.1f}s: {e}")
+        logger.error(traceback.format_exc())
+        try:
+            project_ref.update({'status': 'generation_failed'})
+            _update_progress(project_id, status='failed', phase='error',
+                             error='Guide generation failed. Please try again — no credits were used.')
+        except Exception:
+            pass
 
-                    img_url       = img_future.result()
-                    img_upload_time = time.time() - img_upload_start
-                    logger.info(f"[PROJECT APPROVAL] Step {i+1} image upload completed in {img_upload_time:.3f}s")
 
-                    narration_url = tts_future.result()
-                    tts_time      = time.time() - tts_start
-                    logger.info(f"[PROJECT APPROVAL] Step {i+1} TTS generation completed in {tts_time:.3f}s")
+@app.route('/api/projects/<string:project_id>/approve', methods=['PUT'])
+def approve_project_plan(project_id):
+    """Validates the request, then hands off to a background generation job (202)."""
+    uid = verify_token(request.headers.get('Authorization'))
+    if not uid:
+        return jsonify({'error': 'Unauthorized'}), 401
 
-            except Exception as e:
-                logger.error(f"[PROJECT APPROVAL] ERROR processing step {i+1}: {e}")
+    user_data = db_ref.child(f'users/{uid}').get()
+    if not user_data or user_data.get('credits', 0) < 5:
+        return jsonify({'error': 'Insufficient credits'}), 402
 
-            result.update({
-                "imageUrl":     img_url,
-                "narrationUrl": narration_url,
-                "isDone":       False,
-                "notes":        ""
-            })
-            return i, result
+    project_ref  = db_ref.child(f'projects/{project_id}')
+    project_data = project_ref.get()
+    if not project_data or project_data.get('uid') != uid:
+        return jsonify({'error': 'Project not found or access denied'}), 404
 
-        # Process all steps in parallel (up to 5 steps × 2 sub-tasks each)
-        step_args = [(i, parsed_steps[i], inline_images[i]) for i in range(len(parsed_steps))]
+    if project_data.get('status') == 'generating' and not _progress_is_stale(project_data.get('generationProgress')):
+        return jsonify({'error': 'Guide generation is already in progress'}), 409
+
+    selected_option = (request.get_json(silent=True) or {}).get('selectedOption')
+    logger.info(f"[PROJECT APPROVAL] Queuing generation for project {project_id} (option: {selected_option})")
+
+    now = datetime.utcnow().isoformat()
+    project_ref.update({'status': 'generating'})
+    db_ref.child(f'projects/{project_id}/generationProgress').set({
+        'status':      'generating',
+        'phase':       'planning',
+        'currentStep': 0,
+        'totalSteps':  5,
+        'message':     'Planning your step-by-step guide...',
+        'model':       GENERATION_MODEL,
+        'error':       '',
+        'startedAt':   now,
+        'updatedAt':   now,
+    })
+    threading.Thread(target=_run_guide_generation, args=(uid, project_id, selected_option), daemon=True).start()
+    return jsonify({'status': 'generating', 'projectId': project_id}), 202
 
-        with concurrent.futures.ThreadPoolExecutor(max_workers=len(parsed_steps)) as outer_pool:
-            for i, completed_step in outer_pool.map(process_single_step, step_args):
-                final_steps[i] = completed_step
 
-        step_processing_time = time.time() - step_processing_start
-        logger.info(f"[PROJECT APPROVAL] All steps processing completed in {step_processing_time:.3f}s")
+@app.route('/api/projects/<string:project_id>/progress', methods=['GET'])
+def get_generation_progress(project_id):
+    """Lightweight poll target: project status + generationProgress only."""
+    uid = verify_token(request.headers.get('Authorization'))
+    if not uid:
+        return jsonify({'error': 'Unauthorized'}), 401
 
-        # Database update timing
-        db_update_start = time.time()
-        update_data = {
-            "status":         "ready",
-            "toolsList":      tools_list,
-            "steps":          final_steps,
-            "selectedOption": selected_option or ""
-        }
-        project_ref.update(update_data)
-        logger.info(f"[PROJECT APPROVAL] Updating data in db: {len(update_data)} fields")
-        db_update_time = time.time() - db_update_start
-        logger.info(f"[PROJECT APPROVAL] Database update completed in {db_update_time:.3f}s")
-
-        # Final project fetch timing
-        final_fetch_start = time.time()
-        updated_project = project_ref.get()
-        updated_project["projectId"] = project_id
-        final_fetch_time = time.time() - final_fetch_start
-        logger.info(f"[PROJECT APPROVAL] Final project fetch completed in {final_fetch_time:.3f}s")
-
-        # Credits deduction timing
-        credits_update_start = time.time()
-        user_ref.update({'credits': user_data.get('credits', 0) - 5})
-        credits_update_time = time.time() - credits_update_start
-        logger.info(f"[PROJECT APPROVAL] Credits update completed in {credits_update_time:.3f}s")
-
-        # Total time calculation
-        total_time = time.time() - start_time
-        logger.info(f"[PROJECT APPROVAL] SUCCESS: Project approval completed in {total_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL] TIMING BREAKDOWN:")
-        logger.info(f"[PROJECT APPROVAL]   - Image download: {image_download_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - Image processing: {image_processing_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - Context prep: {context_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - AI generation (Nano Banana 2): {ai_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - Response parsing: {parsing_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - Text extraction: {extraction_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - Step processing (threaded): {step_processing_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - DB update: {db_update_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - Final fetch: {final_fetch_time:.3f}s")
-        logger.info(f"[PROJECT APPROVAL]   - Credits update: {credits_update_time:.3f}s")
-
-        return jsonify(updated_project)
+    project_ref = db_ref.child(f'projects/{project_id}')
+    if project_ref.child('uid').get() != uid:
+        return jsonify({'error': 'Project not found or access denied'}), 404
 
-    except Exception as e:
-        total_time = time.time() - start_time
-        logger.error(f"[PROJECT APPROVAL] ERROR: Exception occurred after {total_time:.3f}s: {e}")
-        logger.error(f"[PROJECT APPROVAL] Error type: {type(e).__name__}")
-        logger.error(f"[PROJECT APPROVAL] Project ID: {project_id}, User ID: {uid}")
-        logger.error(f"[PROJECT APPROVAL] Full traceback: {traceback.format_exc()}")
-        return jsonify({'error': f'Internal server error: {str(e)}'}), 500
+    status   = project_ref.child('status').get()
+    progress = project_ref.child('generationProgress').get()
+
+    # A dead background thread (server restart) leaves the project stuck in
+    # 'generating'; surface it as a retryable failure once the heartbeat is stale.
+    if status == 'generating' and _progress_is_stale(progress):
+        project_ref.update({'status': 'generation_failed'})
+        _update_progress(project_id, status='failed', phase='error',
+                         error='Generation timed out. Please try again — no credits were used.')
+        status   = 'generation_failed'
+        progress = project_ref.child('generationProgress').get()
+
+    return jsonify({'status': status, 'progress': progress})
 
 
 @app.route('/api/projects', methods=['GET'])