mallmaverick-store-scraper 0.1.0

package/src/hoursPipeline.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const {
+  parseJsonLdHours,
+  parseFreeFormHours,
+  parseSchemaOpeningHours,
+  canonicalize,
+  validateCanonical,
+} = require('./hoursParser');
+const { detectsSyncWithMall } = require('./mallContext');
+const { extractHoursWithLLM } = require('./llmExtract');
+const { chooseExternalLink, extractHoursFromExternal } = require('./externalFollow');
+
+/**
+ * Layered hours extraction.
+ *
+ * Layers (high-to-low confidence):
+ *   1. JSON-LD openingHoursSpecification        → 0.98
+ *   2. Microdata itemprop="openingHours"        → 0.95
+ *   3. DOM patterns (table/dl/ul stereotypes)   → 0.90
+ *   4. Labeled section + free-form parse        → 0.85
+ *   5. "Sync with mall hours" phrase            → 0.80   (uses mallContext)
+ *   6. LLM on focused snippet                   → 0.70
+ *   7. External-link follow                     → 0.65   (visits retailer site)
+ *   8. (Vision)                                 → reserved, not implemented in slice 1
+ *
+ * Inputs:
+ *   - pageData: { html, text, jsonLd, metaTags, links?, dom? }
+ *   - opts.mallContext: { canonical } - mall's own hours, if known
+ *   - opts.client, opts.model       - OpenAI for layer 6
+ *   - opts.browser, opts.mallOrigin - for layer 7
+ *   - opts.logger
+ *
+ * Returns:
+ *   { canonical, source, confidence, sync_with_centre_hours }
+ */
+async function extractHours(pageData, opts = {}) {
+  const { mallContext, client, model, browser, mallOrigin, logger } = opts;
+
+  // Layer 1: JSON-LD openingHoursSpecification
+  if (pageData.jsonLd && pageData.jsonLd.length) {
+    const ld = parseJsonLdHours(pageData.jsonLd);
+    if (ld) {
+      const canonical = canonicalize(ld);
+      if (validateCanonical(canonical).ok) {
+        return {
+          canonical, source: 'jsonld', confidence: 0.98, sync_with_centre_hours: false,
+        };
+      }
+    }
+  }
+
+  // Layer 2: Microdata via itemprop in DOM (or meta tags)
+  if (pageData.microdataHours) {
+    const md = parseSchemaOpeningHours(pageData.microdataHours);
+    if (md) {
+      const canonical = canonicalize(md);
+      if (validateCanonical(canonical).ok) {
+        return { canonical, source: 'microdata', confidence: 0.95, sync_with_centre_hours: false };
+      }
+    }
+  }
+
+  // Layer 3: DOM patterns — caller can pre-extract a "hours block" string from
+  // common selectors. If not pre-extracted, we'll skip.
+  if (pageData.domHoursBlock) {
+    const block = parseFreeFormHours(pageData.domHoursBlock);
+    if (block) {
+      const canonical = canonicalize(block);
+      if (validateCanonical(canonical).ok) {
+        return { canonical, source: 'dom', confidence: 0.90, sync_with_centre_hours: false };
+      }
+    }
+  }
+
+  // Layer 4: Labeled section + free-form on page text
+  if (pageData.text) {
+    const labeled = sliceLabeledHoursSection(pageData.text);
+    if (labeled) {
+      const ff = parseFreeFormHours(labeled);
+      if (ff) {
+        const canonical = canonicalize(ff);
+        const v = validateCanonical(canonical);
+        // Accept if we got 5+ days; many sites omit closed-day rows
+        const dayCount = canonical.split(';').filter(Boolean).length;
+        if (v.ok && dayCount >= 5) {
+          return { canonical, source: 'labeled', confidence: 0.85, sync_with_centre_hours: false };
+        }
+      }
+    }
+  }
+
+  // Layer 5: Sync with mall hours
+  if (mallContext && mallContext.canonical && pageData.text && detectsSyncWithMall(pageData.text)) {
+    if (logger) logger.info('   ↳ matched "syncs with mall hours" — using mall hours');
+    return {
+      canonical: mallContext.canonical,
+      source: 'sync-with-mall',
+      confidence: 0.80,
+      sync_with_centre_hours: true,
+    };
+  }
+
+  // Layer 6: LLM on focused snippet
+  if (client && model && pageData.text) {
+    const canonical = await extractHoursWithLLM({ client, model, pageData, logger });
+    if (canonical) {
+      return { canonical, source: 'llm', confidence: 0.70, sync_with_centre_hours: false };
+    }
+  }
+
+  // Layer 7: External-link follow
+  if (browser && pageData.links && mallOrigin) {
+    const chosen = chooseExternalLink(pageData.links, mallOrigin);
+    if (chosen) {
+      if (logger) logger.info(`   ↳ following external link: ${chosen.href}`);
+      const ext = await extractHoursFromExternal(browser, chosen.href, { logger });
+      if (ext) {
+        return {
+          canonical: ext.canonical,
+          source: ext.source,
+          confidence: 0.65,
+          sync_with_centre_hours: false,
+          externalUrl: ext.sourceUrl,
+        };
+      }
+    }
+  }
+
+  return { canonical: '', source: null, confidence: 0, sync_with_centre_hours: false };
+}
+
+/**
+ * Slice the chunk of text that follows a "Hours" heading.
+ * Returns a ~600-char window, or null if no heading-like line is found.
+ */
+function sliceLabeledHoursSection(text) {
+  if (!text) return null;
+  const lines = text.split('\n');
+  const HEADING = /\b(hours of operation|store hours|opening hours|business hours|hours)\b\s*:?$/i;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.length === 0) continue;
+    if (HEADING.test(line) || /^(hours)\s*:?\s*$/i.test(line)) {
+      return lines.slice(i, Math.min(lines.length, i + 16)).join('\n');
+    }
+  }
+  return null;
+}
+
+module.exports = { extractHours, sliceLabeledHoursSection };

package/src/imageExtraction.js

@@ -0,0 +1,331 @@
+'use strict';
+
+const { URL } = require('url');
+
+/**
+ * Enumerate every <img> on the store page and score it for three slots:
+ *   - logoScore   → the store's brand mark
+ *   - brandScore  → hero / banner / lifestyle image
+ *   - frontScore  → exterior storefront photo
+ *
+ * Excludes obvious chrome: map tiles, transparent pixels, mall logos,
+ * developer/parent-company logos, splash/popup images, social-share icons.
+ *
+ * @param {import('puppeteer').Page} page
+ * @param {string} storeUrl
+ * @param {object} ctx  - { storeName, mallName, mallEcosystem (array of domains/hostnames) }
+ * @returns {Promise<Array<{url, alt, w, h, aspect, logoScore, brandScore, frontScore}>>}
+ */
+async function classifyImages(page, storeUrl, {
+  storeName = '', mallName = '', mallEcosystem = [],
+  mallChromeImages = [], storeCardLogos = [],
+} = {}) {
+  let origin = '';
+  try { origin = new URL(storeUrl).origin; } catch (_) {}
+
+  // Effective chrome = images that appear on the mall homepage MINUS those that
+  // are known store-card logos (which often appear in homepage carousels).
+  const cardSet = new Set(storeCardLogos || []);
+  const effectiveChrome = (mallChromeImages || []).filter(u => !cardSet.has(u));
+
+  return await page.evaluate(({ origin, storeName, mallName, mallEcosystem, mallChromeImages: effChrome }) => {
+    const resolve = (src) => {
+      if (!src) return null;
+      if (src.startsWith('data:')) return null;
+      if (src.startsWith('http')) return src;
+      if (src.startsWith('//')) return 'https:' + src;
+      if (src.startsWith('/')) return origin + src;
+      return null;
+    };
+
+    const filenameOf = (u) => {
+      try { return new URL(u).pathname.split('/').pop() || ''; } catch { return ''; }
+    };
+    const hostOf = (u) => {
+      try { return new URL(u).hostname.replace(/^www\./, ''); } catch { return ''; }
+    };
+
+    const cleanName = String(storeName || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+    const mallNameClean = String(mallName || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+    // First significant word of the mall name (e.g. "Currents of Windermere" → "currents")
+    const mallNameTokens = String(mallName || '').toLowerCase()
+      .split(/\W+/).filter(w => w.length >= 4 && !['mall','shopping','centre','center','plaza','village'].includes(w));
+    const mallNameLead = mallNameTokens[0] || '';
+    const ecoHosts = new Set((mallEcosystem || []).map(s => String(s).toLowerCase()));
+    const chromeSet = new Set(effChrome || []);
+
+    // Hard-exclude these obvious non-store images.
+    const HARD_EXCLUDE_URL = /(gstatic\.com|googleusercontent|maps\.googleapis|google\.com\/maps|placeholder|spacer|blank\.gif|transparent\.png|\.svg\?token=|favicon|apple-touch-icon)/i;
+    const HARD_EXCLUDE_FILE = /(splash|noptin|popup|footer-logo|wordmark)/i;
+    const DEVELOPER_HINTS = /(developments?|development[-_]corp|holdings|properties|realty|management|hill[-_]?company|harvard|cameron|cushman|wakefield|jll|brookfield|cadillac|fairview|ivanhoe|cambridge)/i;
+    const SOCIAL_ICON_HINTS = /(facebook[-_]?icon|instagram[-_]?icon|twitter[-_]?icon|x[-_]?icon|tiktok[-_]?icon|youtube[-_]?icon|pinterest[-_]?icon|social[-_]?icon|share[-_]?icon)/i;
+
+    const out = [];
+    document.querySelectorAll('img').forEach(img => {
+      const src = img.currentSrc
+        || img.src
+        || img.getAttribute('data-src')
+        || img.getAttribute('data-lazy-src')
+        || '';
+      const url = resolve(src);
+      if (!url) return;
+      if (HARD_EXCLUDE_URL.test(url)) return;
+      // Skip mall-chrome: any image that also appears on the mall homepage.
+      if (chromeSet.has(url) || chromeSet.has(src)) return;
+
+      const file = filenameOf(url).toLowerCase();
+      if (HARD_EXCLUDE_FILE.test(file)) return;
+
+      const alt = (img.getAttribute('alt') || '').trim();
+      const cls = (img.className || '').toLowerCase();
+      const id = (img.id || '').toLowerCase();
+      const parent = img.parentElement;
+      const parentCls = parent ? (parent.className || '').toLowerCase() : '';
+      const parentTag = parent ? parent.tagName.toLowerCase() : '';
+      const parentId = parent ? (parent.id || '').toLowerCase() : '';
+
+      // Skip social-icon imagery
+      if (SOCIAL_ICON_HINTS.test(file) || SOCIAL_ICON_HINTS.test(cls) || SOCIAL_ICON_HINTS.test(alt)) return;
+
+      // Skip if the host is part of the mall ecosystem (sister property)
+      if (ecoHosts.has(hostOf(url).toLowerCase())) return;
+
+      // Dimensions
+      const w = img.naturalWidth || 0;
+      const h = img.naturalHeight || 0;
+      const rect = img.getBoundingClientRect();
+      const rW = Math.round(rect.width);
+      const rH = Math.round(rect.height);
+      const useW = w || rW;
+      const useH = h || rH;
+      // Skip tiny (likely icons)
+      if (useW < 24 || useH < 24) return;
+
+      const aspect = useH ? useW / useH : 1;
+      const altClean = alt.toLowerCase().replace(/[^a-z0-9]/g, '');
+      const inFooter = !!img.closest('footer') || /footer/.test(parentCls) || /footer/.test(parentId);
+
+      // Detect "this is mall chrome by alt text"
+      // - full mall name in alt (e.g. "Currents of Windermere")
+      // - the leading distinctive token of the mall name (e.g. "Banner - Currents - Events")
+      const altIsMallName = mallNameClean.length >= 4 && altClean.includes(mallNameClean);
+      const altHasMallLead = mallNameLead.length >= 4 && altClean.includes(mallNameLead);
+      if (altIsMallName || altHasMallLead) return;
+      // Same check on the filename (catches `banner-currents-events-1750x900.jpg` etc.)
+      if (mallNameLead.length >= 4 && file.includes(mallNameLead)) return;
+
+      // Detect "this is a developer / parent company logo"
+      if (DEVELOPER_HINTS.test(alt) || DEVELOPER_HINTS.test(file)) return;
+
+      // Footer-positioned imagery is rarely a store-relevant image (it's site chrome).
+      if (inFooter) return;
+
+      // Hard chrome skip: images in banner/hero containers OR with generic
+      // chrome filenames ("WEbsite-Background", "page-banner") that have NO
+      // store-name connection are almost always mall chrome.
+      const cleanName_ = cleanName;
+      const altClean_ = altClean;
+      const inBannerContainerEarly = /banner|hero|masthead|background/.test(cls)
+        || /banner|hero|masthead|background/.test(parentCls)
+        || !!(img.closest && img.closest('.banner, .hero, .masthead, [class*="banner"], [class*="hero"]'));
+      const genericChromeFileEarly = /(^|[-_])(banner|background|hero|masthead|cover|website[-_]?(bg|background)|page[-_]?banner|default)([-_]|\.|$)/i.test(file);
+      const genericChromeAltEarly = /^(banner|background|hero|cover|image|photo|picture)$/i.test((alt || '').trim());
+      const altMatchesStoreEarly = cleanName_.length >= 5
+        && altClean_.length > 0 && altClean_.includes(cleanName_.slice(0, 5));
+      const fileMatchesStoreEarly = cleanName_.length >= 5
+        && file.includes(cleanName_.slice(0, 5));
+      if ((inBannerContainerEarly || genericChromeFileEarly || genericChromeAltEarly)
+          && !altMatchesStoreEarly && !fileMatchesStoreEarly) {
+        return;
+      }
+
+      // ---------- score all three slots ----------
+      let logoScore = 0, brandScore = 0, frontScore = 0;
+
+      // Strongest possible logo signal: filename contains BOTH "logo" and the
+      // store name (e.g. "Barcelos-Logo_website.png", "booster-juice-logo.png").
+      // This beats class="store-logo" because mall CMS templates sometimes
+      // mistakenly tag a placeholder with class="store-logo".
+      if (cleanName.length >= 5 && file.includes(cleanName.slice(0, 5)) && /logo/.test(file)) {
+        logoScore += 130;
+      }
+
+      // Downstream CMSes (imgix-based image services in particular) often have
+      // trouble with GIFs. Penalize so when a PNG/JPG/webp alternative exists
+      // it wins, but a GIF can still be picked if it's the only option.
+      const isGif = /\.gif(\?|$)/i.test(url) || /\.gif$/i.test(file);
+      if (isGif) {
+        logoScore -= 50;
+        brandScore -= 30;
+      }
+      if (/store-logo|tenant-logo|retailer-logo|brand-logo/.test(cls)) logoScore += 100;
+      if (/store-logo|tenant-logo|retailer-logo|brand-logo/.test(parentCls)) logoScore += 80;
+      if (/\blogo\b/.test(cls) || /\blogo\b/.test(id) || /\blogo\b/.test(parentCls)) logoScore += 30;
+      if (/logo/.test(file)) logoScore += 40;
+      if (cleanName.length >= 3 && altClean.includes(cleanName.slice(0, Math.min(cleanName.length, 8)))) {
+        logoScore += 60;
+      }
+      // Aspect: logos are roughly square (0.5–2.0)
+      if (aspect >= 0.5 && aspect <= 2.0) logoScore += 15;
+      else logoScore -= 10;
+      // Size sweet spot
+      if (useW >= 60 && useW <= 600 && useH >= 60 && useH <= 600) logoScore += 15;
+      if (useW > 1000 || useH > 800) logoScore -= 15;
+      // In content area is a bonus
+      if (parent && parent.closest && parent.closest('article, main, .content, [class*="content"], [class*="store"]')) logoScore += 10;
+      // og:image is rarely a logo
+      // (handled below outside the loop)
+
+      // ---------- score brand / hero ----------
+      if (/banner|hero|feature|cover|masthead|brand-image|brand_image/.test(cls)) brandScore += 80;
+      if (/banner|hero|feature|cover|masthead/.test(parentCls)) brandScore += 80;
+      if (/banner|hero|feature|cover|background/.test(file)) brandScore += 40;
+      if (aspect > 1.8) brandScore += 25;
+      if (useW > 800) brandScore += 15;
+      if (parent && parent.closest && parent.closest('[class*="banner"], [class*="hero"], [class*="feature"]')) brandScore += 20;
+      // Brand images are usually NOT square — penalize square big images so we don't pick a logo here
+      if (aspect >= 0.85 && aspect <= 1.15 && useW <= 400) brandScore -= 30;
+
+      // (chrome detection happens earlier; this block intentionally left empty)
+
+      // ---------- score storefront ----------
+      if (/(storefront|store[-_]?front|exterior|outside|building|facade)/.test(cls)
+       || /(storefront|store[-_]?front|exterior|outside|building|facade)/.test(parentCls)) frontScore += 100;
+      if (/(storefront|store[-_]?front|exterior|outside|building|facade)/.test(file)) frontScore += 80;
+      if (/exterior|outside|store ?front|front (of|view)/i.test(alt)) frontScore += 60;
+      if (parentTag === 'figure') frontScore += 10;
+      if (aspect >= 1.2 && aspect <= 1.9) frontScore += 8;
+
+      out.push({
+        url,
+        alt,
+        cls,
+        parentCls,
+        file,
+        w: useW,
+        h: useH,
+        aspect: Math.round(aspect * 100) / 100,
+        top: Math.round(rect.top),
+        logoScore,
+        brandScore,
+        frontScore,
+      });
+    });
+
+    // og:image as a candidate (usually a hero/feature image for a store page)
+    const og = document.querySelector('meta[property="og:image"]');
+    if (og) {
+      const ogUrl = resolve(og.getAttribute('content'));
+      if (ogUrl && !HARD_EXCLUDE_URL.test(ogUrl)) {
+        out.push({
+          url: ogUrl, alt: 'og:image', cls: '', parentCls: '', file: '',
+          w: 0, h: 0, aspect: 0, top: -1,
+          logoScore: 5, brandScore: 30, frontScore: 5,
+        });
+      }
+    }
+
+    return out;
+  }, { origin, storeName, mallName, mallEcosystem, mallChromeImages: effectiveChrome });
+}
+
+/**
+ * Given the classifier output and the directoryLogoUrl, choose final URLs for
+ * { logo_image_url, brand_image_url, store_front_image_url }.
+ *
+ * Logic:
+ *   - LOGO: highest logoScore. directoryLogoUrl is treated as a candidate with
+ *     a baseline logoScore boost — but if a store-page candidate scores higher
+ *     and clearly looks like a logo (logoScore >= 80), prefer it.
+ *   - BRAND: highest brandScore among remaining candidates with brandScore >= 30.
+ *   - FRONT: highest frontScore among remaining candidates with frontScore >= 50.
+ *
+ * Logos never get reused in brand/front slots, and vice versa.
+ */
+function pickImages(candidates, { directoryLogoUrl, storeName = '' } = {}) {
+  const cleanName = String(storeName || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+  // Dedup by URL (keep highest scores across duplicates)
+  const map = new Map();
+  for (const c of candidates) {
+    if (!c.url) continue;
+    const key = c.url;
+    const existing = map.get(key);
+    if (!existing) { map.set(key, { ...c }); continue; }
+    existing.logoScore = Math.max(existing.logoScore, c.logoScore);
+    existing.brandScore = Math.max(existing.brandScore, c.brandScore);
+    existing.frontScore = Math.max(existing.frontScore, c.frontScore);
+  }
+
+  // Inject directoryLogoUrl as a candidate if not already present.
+  if (directoryLogoUrl && !map.has(directoryLogoUrl)) {
+    map.set(directoryLogoUrl, {
+      url: directoryLogoUrl,
+      alt: '', cls: '', parentCls: '', file: '',
+      w: 0, h: 0, aspect: 0, top: 0,
+      logoScore: 75,    // baseline trust for the listing card image
+      brandScore: 0,
+      frontScore: 0,
+    });
+  } else if (directoryLogoUrl && map.has(directoryLogoUrl)) {
+    // Boost the existing entry's logoScore — it appeared on the listing card.
+    map.get(directoryLogoUrl).logoScore += 25;
+  }
+
+  const all = Array.from(map.values());
+  const used = new Set();
+
+  // LOGO selection — descriptive filename beats class-based signal.
+  //
+  // Step 1: among ALL candidates that pass the qualifier, see if any has BOTH
+  //         "logo" and the store name in the URL. That's the most authoritative
+  //         possible signal of a real logo file — pick the highest-scoring such.
+  // Step 2: otherwise fall back to top by logoScore.
+  const logoSorted = [...all].sort((a, b) => b.logoScore - a.logoScore);
+  const logoQualified = logoSorted.filter(c => c.logoScore >= 40);
+  let logo = null;
+  if (logoQualified.length > 0) {
+    if (cleanName.length >= 5) {
+      const namedLogo = logoQualified.find(c =>
+        /logo/i.test(c.url) && c.url.toLowerCase().includes(cleanName.slice(0, 5))
+      );
+      if (namedLogo) logo = namedLogo;
+    }
+    if (!logo) logo = logoQualified[0];
+  }
+  if (logo) used.add(logo.url);
+
+  // BRAND
+  const brandSorted = all
+    .filter(c => !used.has(c.url))
+    .sort((a, b) => b.brandScore - a.brandScore);
+  let brand = null;
+  for (const c of brandSorted) {
+    if (c.brandScore >= 40) { brand = c; break; }
+  }
+  if (brand) used.add(brand.url);
+
+  // STOREFRONT
+  const frontSorted = all
+    .filter(c => !used.has(c.url))
+    .sort((a, b) => b.frontScore - a.frontScore);
+  let front = null;
+  for (const c of frontSorted) {
+    if (c.frontScore >= 50) { front = c; break; }
+  }
+
+  return {
+    logo_image_url: logo ? logo.url : '',
+    brand_image_url: brand ? brand.url : '',
+    store_front_image_url: front ? front.url : '',
+    logo_image_url_alt_text: logo ? logo.alt : '',
+    brand_image_url_alt_text: brand ? brand.alt : '',
+    store_front_image_url_alt_text: front ? front.alt : '',
+    _imageDecisions: {
+      logoScore: logo ? logo.logoScore : 0,
+      brandScore: brand ? brand.brandScore : 0,
+      frontScore: front ? front.frontScore : 0,
+    },
+  };
+}
+
+module.exports = { classifyImages, pickImages };

package/src/llmExtract.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const {
+  parseFreeFormHours,
+  canonicalize,
+  validateCanonical,
+} = require('./hoursParser');
+
+const HOURS_KEYWORDS = /\b(hours?|open(?:ing)?|closed|monday|tuesday|wednesday|thursday|friday|saturday|sunday|mon\b|tue\b|wed\b|thu\b|fri\b|sat\b|sun\b)/i;
+
+/**
+ * Locate hours-relevant snippets in raw page text.
+ * Returns up to maxSnippets windows of ~window chars around keyword hits.
+ */
+function findHoursSnippets(text, { window: w = 400, maxSnippets = 3 } = {}) {
+  if (!text) return [];
+  const cleaned = text.replace(/\r/g, '');
+  const snippets = [];
+  const seen = new Set();
+
+  const lines = cleaned.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!HOURS_KEYWORDS.test(lines[i])) continue;
+    // Gather surrounding lines
+    const start = Math.max(0, i - 3);
+    const end = Math.min(lines.length, i + 8);
+    const slice = lines.slice(start, end).join('\n').trim();
+    if (!slice || slice.length < 8) continue;
+    if (seen.has(slice)) continue;
+    seen.add(slice);
+    snippets.push(slice.slice(0, w * 2));
+    if (snippets.length >= maxSnippets) break;
+  }
+  return snippets;
+}
+
+/**
+ * Ask the LLM to extract hours from a focused snippet.
+ * Returns canonical string or '' on failure.
+ */
+async function llmExtractHoursFromSnippet(client, model, snippet, logger) {
+  if (!snippet || !snippet.trim()) return '';
+
+  const systemPrompt =
+    `You extract retail store opening hours from short text snippets and return ONLY JSON.
+Rules:
+- Output JSON: { "hours": { "Monday": "10:00 AM - 9:00 PM", "Tuesday": "...", ..., "Sunday": "..." } }
+- Use full day names as keys (Monday..Sunday).
+- Use exactly "H:MM AM/PM - H:MM AM/PM" for open/close.
+- Use "Closed" for closed days.
+- Omit a day if the snippet does not state hours for it. Do not invent.
+- If the snippet does not contain any operating hours, return { "hours": {} }.`;
+
+  const userPrompt = `Snippet:\n"""\n${snippet}\n"""\n\nExtract the hours as JSON.`;
+
+  const isGpt5Family = /^gpt-5(\.|-|$)/i.test(model);
+  const params = {
+    model,
+    messages: [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userPrompt },
+    ],
+    response_format: { type: 'json_object' },
+  };
+  if (isGpt5Family) params.max_completion_tokens = 600;
+  else { params.max_tokens = 600; params.temperature = 0.0; }
+
+  try {
+    const resp = await client.chat.completions.create(params);
+    const raw = JSON.parse(resp.choices[0].message.content);
+    const hours = raw && raw.hours;
+    if (!hours || typeof hours !== 'object' || Object.keys(hours).length === 0) return '';
+    // Round-trip through parser to canonicalize and validate format
+    const lines = Object.entries(hours).map(([d, v]) => `${d}: ${v}`).join('\n');
+    const parsed = parseFreeFormHours(lines);
+    if (!parsed) return '';
+    return canonicalize(parsed);
+  } catch (err) {
+    if (logger) logger.warn(`   ⚠ LLM hours extract failed: ${err.message}`);
+    return '';
+  }
+}
+
+/**
+ * Run LLM extraction over the best snippets found in pageData.text.
+ * Returns the first canonical string that passes validation.
+ */
+async function extractHoursWithLLM({ client, model, pageData, logger }) {
+  const snippets = findHoursSnippets(pageData.text || '', { maxSnippets: 3 });
+  if (snippets.length === 0) return '';
+
+  for (const snip of snippets) {
+    const canonical = await llmExtractHoursFromSnippet(client, model, snip, logger);
+    if (canonical && validateCanonical(canonical).ok) return canonical;
+  }
+  return '';
+}
+
+module.exports = { findHoursSnippets, llmExtractHoursFromSnippet, extractHoursWithLLM };