---
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:
```env
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:**
  ```bash
  ./run.sh db
  ```
* **Launch the Web Server:**
  ```bash
  ./run.sh
  ```
* **Verify Code Format & Quality:**
  ```bash
  ./run.sh verify
  ```