coles-invoice-processor

name	coles-invoice-processor
description	Processes Coles grocery invoices to extract structured data and predict future orders. Use when user uploads/pastes invoice content, asks to analyze grocery purchases, or wants shopping predictions.

Coles Invoice Processor Skill

Analyze Coles grocery store invoices using Python scripts to convert PDFs, extract structured data, and predict future orders with budget forecasts.

When to Use This Skill

Activate when the user:

• Uploads Coles invoice PDFs or images
• Pastes invoice text content
• Asks to extract grocery item data
• Wants to analyze shopping history
• Requests future order predictions
• Needs shopping budget estimates

Setup Requirements

Before using the scripts, ensure dependencies are installed:

# Create virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Required packages: pymupdf4llm, pandas, prophet

Pipeline Overview

The processing pipeline consists of 3 main scripts:

1. 01_convert.py - Convert PDFs to Markdown
2. 03_extract_data.py - Extract structured data from Markdown
3. 04_predict_orders.py - Predict future orders and budget

How to Process Invoices

Step 1: Place Invoice PDFs

Place Coles invoice PDFs in the input_invoices/ directory.

Step 2: Convert PDFs to Markdown

python 01_convert.py

This converts each PDF in input_invoices/ to a Markdown file in the same folder using pymupdf4llm.

Step 3: Extract Structured Data

python 03_extract_data.py

Parses the Markdown invoices and extracts:

• Invoice metadata (number, date, time)
• Categories and items
• Product names, quantities, prices, weights

Output: output_extracted/extracted_data.json

Step 4: Predict Future Orders

python 04_predict_orders.py

Analyzes purchase history and:

• Calculates average purchase intervals per product
• Determines typical quantities
• Forecasts ~150 days of future orders
• Groups orders within 3 days
• Merges small orders (<$50) with adjacent orders within 6 days
• Generates monthly budget estimates

Data Extraction Details

The extraction script parses Markdown looking for:

Invoice Metadata:

• Invoice number: **Invoice number:** #123456
• Invoice date: **Invoice date:** 7 December 2024
• Invoice time: **Invoice time:** 14:30:00

Product Categories: Categories appear as bold headers (e.g., **Dairy**, **Bakery**, **Meat & Seafood**)

Product Line Items: Format: [Product Name](link) Ordered Picked UnitPrice TotalPrice

Example:

[Coles Full Cream Milk 3L](https://...) 2 2 $4.65 $9.30

Extracted fields:

• Product name (including weight/size from name like "3L", "500g", "1kg")
• Quantity ordered
• Quantity picked
• Unit price
• Total price

Output Formats

Extracted Data JSON Schema

{
  "filename": "ea[REDACTED]_044712.md",
  "invoice_number": "[REDACTED]",
  "invoice_date": "7 December 2024",
  "invoice_time": "14:30:00",
  "categories": [
    {
      "name": "Dairy",
      "items": [
        {
          "product": "Coles Full Cream Milk 3L",
          "weight": "3L",
          "link": "https://...",
          "ordered": "2",
          "picked": "2",
          "unit_price": "$4.65",
          "total_price": "$9.30"
        
      
    
  

Predicted Orders Output

Order #1 - Approx Date: 2025-12-15 - Total Est. Cost: $95.50
Product                                            | Qty   | Unit $   | Total $
--------------------------------------------------------------------------------
Coles Full Cream Milk 3L...                        | 2     | $4.65    | $9.30

Monthly Budget Output

--- Estimated Monthly Budget ---
2025-December: $785.80
2026-January: $738.55
2026-February: $692.40

Privacy Notes

• Invoice numbers are automatically redacted in filenames and output
• Filenames like ea12345_67890.md become ea[REDACTED]_67890.md
• Sensitive personal information should be manually reviewed
• Focus on product and pricing data only

Common Categories in Coles Invoices

• Dairy
• Bakery
• Meat & Seafood
• Fruit & Vegetables
• Pantry
• Frozen
• Drinks
• Health & Beauty
• Baby
• Household