title: Shelf Scribe
emoji: 📋
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 6.16.0
app_file: app.py
pinned: false
license: mit
short_description: AI restocking and pricing assistant for small retail shops.
Shelf Scribe: AI Retail Restocking & Pricing Assistant
Shelf Scribe is an AI-assisted retail workflow optimizer designed specifically for small, independent shop owners, convenience stores, kiosks, grocery stores, and pharmacies. It turns messy photos of store shelves and supplier invoices/receipts into a practical, action-oriented restocking and pricing dashboard.
Instead of positioning this as a fully autonomous (and risky) inventory system, Shelf Scribe serves as an AI-assisted restock and shelf-label checklist. The human shop owner remains in control, reviewing pricing suggestions, editing the catalog, and confirming supplier orders.
🚀 Key Features & Hackathon Merit Badges
- Double Execution Flow: Supports Cached Demo Mode for fast, local, offline testing during judging, alongside Live VLM Inference Mode to process user uploads.
- Deterministic Reconciliation: Uses a custom Python engine with fuzzy name matching and alias lookups to align messy visual OCR text with catalog entries.
- Reorder Calculations with Pack Rounding: Auto-flags low-stock items and rounds up reorder recommendations to whole pack sizes (e.g. cartons of 12 or 24).
- Margin Auditing: Compares invoice costs with catalog prices and alerts the owner if wholesale price hikes violate their target gross profit margins.
- Outputs Ready for Action: Generates a copy-to-clipboard WhatsApp message to order items, plus print-ready shelf labels in HTML and PDF layouts.
- Local-First Database: Uses a lightweight SQLite database (
shelf_scribe.db) to persist the product catalog, edit settings, and track detections.
📦 Project Layout
.
├── app.py # Main Gradio application interface
├── config.py # Centralized configuration and environment settings
├── database.py # Root database connection wrapper
├── models.py # LLM loading and structured extraction triggers
├── reconciliation.py # Fuzzy matcher, pricing checks, PO & label HTML formatting
├── pdf_generator.py # Compiles purchase orders and label sheets using ReportLab
├── requirements.txt # Python dependency lists
├── run.sh # Executable runner script with venv auto-activation
├── verify_code.py # Code quality verification (lint & format)
├── pyrightconfig.json # Python type checker configuration
├── database/ # SQLite connection and schema layer
│ ├── __init__.py
│ ├── connection.py # Global SQLite connection pool
│ ├── schema.py # Database tables creation statements
│ └── seed.py # Seeding products catalog database
├── demo_data/ # Pre-computed VLM extraction outputs (JSON)
│ ├── snacks_cached.json
│ ├── drinks_cached.json
│ └── toiletries_cached.json
├── docs/ # Detailed hackathon documentation
│ ├── PROJECT_BRIEF.md # Detailed problem definition and business fit
│ ├── ARCHITECTURE.md # Algorithmic flows and database design
│ ├── DEMO_SCRIPT.md # Testing script for hackathon judges
│ └── DATA_COLLECTION_GUIDE.md # Store photography guidelines
└── static/ # Client-side style overrides and javascript utilities
├── style.css # Premium retail dark-mode CSS styles
├── script.js # Clipboard copying, toast notifications, window print
└── demo_images/ # Synthetic photos for demo scenarios
├── snacks_shelf.png
├── drinks_shelf.png
└── toiletries_shelf.png
🔧 Local Installation & Execution
1. Prerequisites
Get a Hugging Face API write token with access to gated model repositories.
2. Set Up Environment Variables
Create a .env file in the root directory:
HF_TOKEN=your_huggingface_write_token_here
3. Run Using the Runner Script
The ./run.sh script automatically detects, activates, and configures the Python virtual environment:
- Initialize the Database:
./run.sh db - Launch the Web Server:
./run.sh - Verify Code Format & Quality:
./run.sh verify