PantryPilot

PantryPilot is a local-first AI pantry assistant for turning receipt uploads into inventory, tracking freshness, and requesting practical dinner suggestions from what is already on hand.

The project is intentionally scoped as a personal/local MVP: SQLite persistence, a FastAPI backend, a Next.js dashboard, deterministic inventory rules, and a narrow AI provider boundary for receipt parsing, image OCR, and meal suggestions.

What It Shows

• Local-first product architecture with explicit post-MVP boundaries.
• Receipt import workflows for text files and receipt images.
• AI provider isolation instead of provider-specific logic leaking through the app.
• Inventory normalization, expiration estimates, and freshness states.
• A simple dashboard for upload, inventory review, and dinner suggestions.
• Focused backend and frontend tests around the main workflow.

Project Layout

• backend/ - API, persistence, receipt ingestion, inventory logic, and AI provider boundaries.
• frontend/ - User interface for inventory, receipt upload, and meal suggestions.
• docs/ - Short product, setup, and architecture notes.

Docs

• MVP scope
• Local setup
• Architecture
• AI provider boundary
• MVP smoke test

Current Assumptions

• The MVP starts local-first.
• No production hosting is configured yet.
• No cloud backend is configured yet.
• No authentication is configured yet.
• Image receipt OCR sends uploaded images to the configured AI provider.
• Local receipt and inventory data are stored in the local SQLite database.

Demo Flow

1. Start the backend and frontend locally.
2. Upload a .txt, .jpg, or .png receipt.
3. Extract receipt text and parse grocery line items through the AI provider boundary.
4. Append parsed groceries to local inventory with expiration estimates.
5. Review inventory freshness and request one dinner suggestion.

Local Setup

Backend:

cd backend
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
cp .env.example .env
# Add a local OPENAI_API_KEY value to .env.
PYTHONPATH=src python -m pantry_pilot

Backend tests:

cd backend
. .venv/bin/activate
PYTHONPATH=src python -m unittest discover -s tests

Create a database migration:

cd backend
. .venv/bin/activate
PYTHONPATH=src python -m alembic revision --autogenerate -m "describe change"

Apply database migrations:

cd backend
. .venv/bin/activate
PYTHONPATH=src python -m alembic upgrade head

Receipt import API:

• POST /receipts/imports accepts multipart/form-data with a file upload.
• Supported upload types are text/plain, image/jpeg, and image/png.
• Text receipts are extracted and parsed synchronously for the local MVP.
• Image receipts are sent to the configured AI provider for OCR text extraction.
• GET /receipts/imports/{id} returns import status, safe error text, and parsed item count.
• Completed imports append new inventory rows for each parsed item. The MVP does not merge duplicates yet; repeated receipts intentionally create separate inventory rows with source set to receipt_import:{id}.
• Created inventory rows include deterministic expiration estimates and freshness status.

Frontend:

cd frontend
npm install
npm run dev

Frontend tests:

cd frontend
npm test

Frontend lint/build check:

cd frontend
npm run lint

Privacy And Production Notes

• This is not a production-hosted app.
• There is no authentication, account system, cloud sync, or multi-user household model.
• Do not expose the development backend directly to the public internet.
• Do not commit .env, local SQLite databases, or real receipt files.
• Image OCR sends the uploaded image to the configured AI provider.