Receipt Manager
Overview
A skill for recording, organizing, and querying personal receipts. It provides a SQLite database for storing receipt data and a CLI script (receipt_db.py) for CRUD operations.
OCR (Automatic Text Recognition)
This skill uses a VLM-first approach for best accuracy.
When adding a receipt:
- Primary: Use VLM model capability or MCP (e.g., understand_image) to extract receipt details
- Backup: Use Tesseract OCR for verification/fallback
tesseract <image_path> - --psm 4
- Compare results - use VLM as primary, OCR as validation
- Extract: vendor name, date, total amount, line items
- Verify the extracted data and correct if needed
Why VLM? Vision language models accurately read receipt details including line items, which Tesseract often misreads.
Data Storage
- Database:
data/receipts/db.sqlite3
- Images (permanent):
data/receipts/images/ — stored with SHA256 hash name, auto-dedup
- Images (temp):
data/receipts/images_tmp/ — temp location for incoming images
The database schema includes: id, vendor, receipt_date, total, currency, category, image_path, image_sha256, text, items_json.
Quick Start
1. Add a Receipt
When user sends a receipt image:
- Copy image to
data/receipts/images_tmp/<timestamp>.jpg
- Use VLM model or MCP to extract details
- (Optional) Verify with Tesseract:
tesseract <image_path> - --psm 4
- Run:
python3 scripts/receipt_db.py add --image <temp_image_path>
- Auto computes SHA256, copies to
images/<sha256>.jpg, removes temp file
- Override with: `--vendor "..." --date "..." --total ... --currency ... --category "..." --items-json '[...]'
2. List Receipts
python3 scripts/receipt_db.py search --q ""
3. Monthly Summary
python3 scripts/receipt_db.py summary --month YYYY-MM
Commands
add: Add new receipt (requires --image)search: Search receipts by keywordshow: Show receipt details by IDsummary: Monthly spending summaryupdate: Update receipt fieldsdelete: Delete receipt by ID
Duplicate Detection
Before adding a new receipt, check for duplicates:
Query existing receipts by vendor + receipt_date + total:
import sqlite3
conn = sqlite3.connect('data/receipts/db.sqlite3')
cursor = conn.cursor()
cursor.execute('''
SELECT id, vendor, receipt_date, total, currency, category, items_json
FROM receipts
WHERE vendor = ? AND receipt_date = ? AND total = ?
''', (vendor, date, total))
If duplicate found:
- Compare fields (vendor, date, total, currency, category, items_json)
- List differences to user
- Ask: "Duplicate receipt found. Differences: ... Replace?"
- If yes, delete old one and add new; if no, skip
If no duplicate: Proceed with normal add flow
Natural Language Query
Use the NLP mode for natural language queries:
python3 scripts/receipt_db.py nlp --text "查吹风机在哪个收据"
python3 scripts/receipt_db.py nlp --text "列出2月shopping类收据"
python3 scripts/receipt_db.py nlp --text "汇总 2026-02"
Resources
scripts/
receipt_db.py: Main CLI tool for receipt management
1---2name: openclaw-receipt-manager3description: Receipt Manager4---56# Receipt Manager78## Overview910A skill for recording, organizing, and querying personal receipts. It provides a SQLite database for storing receipt data and a CLI script (`receipt_db.py`) for CRUD operations.1112## OCR (Automatic Text Recognition)1314**This skill uses a VLM-first approach for best accuracy.**1516When adding a receipt:171. **Primary**: Use VLM model capability or MCP (e.g., understand_image) to extract receipt details182. **Backup**: Use Tesseract OCR for verification/fallback19 ```bash20 tesseract <image_path> - --psm 421 ```223. Compare results - use VLM as primary, OCR as validation234. Extract: vendor name, date, total amount, line items245. Verify the extracted data and correct if needed2526**Why VLM?** Vision language models accurately read receipt details including line items, which Tesseract often misreads.272829## Data Storage3031- **Database:** `data/receipts/db.sqlite3`32- **Images (permanent):** `data/receipts/images/` — stored with SHA256 hash name, auto-dedup33- **Images (temp):** `data/receipts/images_tmp/` — temp location for incoming images3435The database schema includes: id, vendor, receipt_date, total, currency, category, image_path, image_sha256, text, items_json.3637## Quick Start3839### 1. Add a Receipt4041When user sends a receipt image:421. Copy image to `data/receipts/images_tmp/<timestamp>.jpg`432. Use VLM model or MCP to extract details443. (Optional) Verify with Tesseract: `tesseract <image_path> - --psm 4`454. Run: `python3 scripts/receipt_db.py add --image <temp_image_path>`46 - Auto computes SHA256, copies to `images/<sha256>.jpg`, removes temp file47 - Override with: `--vendor "..." --date "..." --total ... --currency ... --category "..." --items-json '[...]'4849### 2. List Receipts5051```bash52python3 scripts/receipt_db.py search --q ""53```5455### 3. Monthly Summary5657```bash58python3 scripts/receipt_db.py summary --month YYYY-MM59```6061## Commands6263- `add`: Add new receipt (requires --image)64- `search`: Search receipts by keyword65- `show`: Show receipt details by ID66- `summary`: Monthly spending summary67- `update`: Update receipt fields68- `delete`: Delete receipt by ID6970## Duplicate Detection7172Before adding a new receipt, check for duplicates:73741. **Query existing receipts** by vendor + receipt_date + total:75 ```python76 import sqlite377 conn = sqlite3.connect('data/receipts/db.sqlite3')78 cursor = conn.cursor()79 cursor.execute('''80 SELECT id, vendor, receipt_date, total, currency, category, items_json81 FROM receipts 82 WHERE vendor = ? AND receipt_date = ? AND total = ?83 ''', (vendor, date, total))84 ```85862. **If duplicate found:**87 - Compare fields (vendor, date, total, currency, category, items_json)88 - List differences to user89 - Ask: "Duplicate receipt found. Differences: ... Replace?"90 - If yes, delete old one and add new; if no, skip91923. **If no duplicate:** Proceed with normal add flow9394---9596## Natural Language Query9798Use the NLP mode for natural language queries:99```bash100python3 scripts/receipt_db.py nlp --text "查吹风机在哪个收据"101python3 scripts/receipt_db.py nlp --text "列出2月shopping类收据"102python3 scripts/receipt_db.py nlp --text "汇总 2026-02"103```104105## Resources106107### scripts/108- `receipt_db.py`: Main CLI tool for receipt management
clinchcc