Weekly Supermarket Flyers Scraper (FlyerScout AI)

Project Purpose & Overview

Supermarket promotional flyers and inserts (encartes) are traditionally published as image carousels on social media platforms like Instagram. Manually reviewing these flyers to track grocery price trends, compare competitor deals, or compile purchasing reports is tedious, error-prone, and time-consuming.

FlyerScout AI converts this manual process into a 100% autonomous pipeline. It crawls target supermarket Instagram accounts, leverages multimodal Vision AI (Google Gemini Flash / GPT-4o) to extract product names and promotional prices directly from images, categorizes items, deduplicates deals with SHA-256 hashes in SQLite, and pushes daily digests and multi-tab Excel workbooks straight to Telegram.

Architecture & Key Features

• Autonomous Social Scraping: Extracts new promotional posts and multi-image carousels from supermarket Instagram profiles using headless Apify actors with custom date filtering.
• Multimodal Vision AI Extraction: Powered by Google Gemini 1.5 Flash (and OpenAI GPT-4o) for ultra-fast, highly accurate optical comprehension of complex flyer layouts, prices, brands, and units.
• Smart Categorization & Normalization: Automatically maps raw extracted items into categories (Meats, Beverages, Grocery, Dairy, Produce, Cleaning, Hygiene, General Merchandise).
• Deduplicated SQLite Storage: Generates unique SHA-256 hashes (supermarket + item + price + date) to prevent repeated deals and maintain an indexed historical database (data/offers.db).
• Telegram Bot Notification Engine: Formats daily deal digests and automatically delivers structured Excel spreadsheets (.xlsx with tabs per supermarket and category) directly to private chats or broadcast channels.
• 100% Cloud Automation (GitHub Actions): Runs scheduled daily cron workflows in the cloud at 07:00 AM without requiring local server uptime, auto-committing updated database snapshots back to the repository.
• Interactive Web Dashboard: Built with FastAPI + Vanilla CSS for live real-time pipeline monitoring, deal search, profile management, and manual execution.

Technical Highlights