Skip to main content

Wine Cellar Management Application with OCR label scanning

Project description

WineBox

A wine cellar management application with OCR label scanning.

Features

  • Label Scanning: Upload wine label images for automatic text extraction via AI
  • Wine Autocomplete: Search 100K+ wines from the X-Wines dataset with community ratings
  • Inventory Tracking: Check-in and check-out bottles with full history
  • Smart Parsing: Automatically identifies vintage, grape variety, region, and more
  • Search: Find wines by any criteria
  • Web Interface: Simple, mobile-friendly interface

Quick Start

Prerequisites

Installation

From PyPI:

pip install winebox

From source:

# Clone the repository
git clone https://github.com/jdrumgoole/winebox.git
cd winebox

# Install dependencies
uv sync --all-extras

# Start MongoDB (using Docker)
docker run -d -p 27017:27017 --name mongodb mongo:7

# Install Tesseract OCR (optional)
# macOS:
brew install tesseract

# Ubuntu/Debian:
sudo apt-get install tesseract-ocr

Configuration

WineBox uses TOML configuration files:

# Copy example configuration
cp config/config.toml.example config.toml
cp config/secrets.env.example secrets.env

# Edit secrets.env with your API keys
nano secrets.env

See the Configuration Guide for full details.

Running the Server

# Development mode with auto-reload
invoke start --reload

# Background mode
invoke start-background

# Check status
invoke status

# Stop server
invoke stop

Access the Application

Configuration

WineBox uses a TOML-based configuration system with separate secrets management:

File Purpose
config.toml Main configuration (server, database, features)
secrets.env Sensitive credentials (API keys)

Configuration Locations

Files are searched in priority order:

  1. ./config.toml - Project root (development)
  2. ~/.config/winebox/config.toml - User config
  3. /etc/winebox/config.toml - System config (production)

Example config.toml

[server]
host = "127.0.0.1"
port = 8000
debug = false

[database]
mongodb_url = "mongodb://localhost:27017"
mongodb_database = "winebox"

[ocr]
use_claude_vision = true

[email]
backend = "console"

Example secrets.env

WINEBOX_SECRET_KEY=your-secret-key-here
WINEBOX_ANTHROPIC_API_KEY=sk-ant-api03-...

Environment variables can override any configuration value.

Usage

Check In Wine

  1. Navigate to the Check In page
  2. Upload front label image (required)
  3. Optionally upload back label image
  4. Review/edit auto-detected wine details
  5. Set quantity and add notes
  6. Click "Check In Wine"

Check Out Wine

  1. Go to the Cellar view
  2. Click "Check Out" on a wine card
  3. Enter quantity to remove
  4. Add optional notes (tasting notes, occasion)
  5. Confirm checkout

Search

Use the Search page to find wines by:

  • Text search (name, winery, region)
  • Vintage year
  • Grape variety
  • Region or country
  • Stock status

API

Full REST API available at /api:

Endpoint Method Description
/api/wines/checkin POST Add wine to cellar
/api/wines/{id}/checkout POST Remove wine from cellar
/api/wines GET List all wines
/api/wines/{id} GET Get wine details
/api/cellar GET Current inventory
/api/cellar/summary GET Cellar statistics
/api/transactions GET Transaction history
/api/search GET Search wines
/api/xwines/search GET Autocomplete wine search
/api/xwines/wines/{id} GET X-Wines wine details
/api/xwines/stats GET Dataset statistics

See /docs for interactive API documentation.

Data Storage

Database

WineBox uses MongoDB for data storage. Configure the connection in config.toml:

[database]
mongodb_url = "mongodb://localhost:27017"
mongodb_database = "winebox"

Images

Wine label images are stored in the data/images/ directory by default.

Item Default Location Config Key
Database MongoDB winebox database.mongodb_database
Images data/images/ storage.data_dir

Note: Back up your MongoDB database and images directory regularly.

X-Wines Dataset

WineBox integrates the X-Wines dataset for wine autocomplete, providing suggestions from 100,646 wines with 21 million community ratings.

Installing the Dataset

# Option 1: Test dataset (100 wines, for development)
uv run python deploy/import_xwines_mongo.py --version test

# Option 2: Full dataset (100K+ wines, for production)
# First, download from Google Drive
uv pip install gdown
mkdir -p data/xwines
uv run gdown --folder "https://drive.google.com/drive/folders/1LqguJNV-aKh1PuWMVx5ELA61LPfGfuu_?usp=sharing" -O data/xwines/
cp data/xwines/X-Wines_Official_Repository/last/XWines_Full_*.csv data/xwines/

# Then import
uv run python deploy/import_xwines_mongo.py --version full

The autocomplete appears when typing in the Wine Name field during check-in.

Label Scanning

WineBox uses AI-powered label scanning to extract wine information from photos.

Claude Vision (Recommended)

For best results, configure Claude Vision by adding your API key to secrets.env:

WINEBOX_ANTHROPIC_API_KEY=your-api-key

Claude Vision provides intelligent label analysis that:

  • Handles decorative and artistic fonts
  • Understands wine-specific terminology
  • Extracts structured data (winery, vintage, grape variety, region, etc.)
  • Works with curved or angled text

Tesseract OCR (Fallback)

If no Anthropic API key is configured, WineBox falls back to Tesseract OCR:

# macOS
brew install tesseract

# Ubuntu/Debian
sudo apt-get install tesseract-ocr

To force Tesseract only (save API costs during development):

# config.toml
[ocr]
use_claude_vision = false

Authentication

WineBox requires authentication for all API endpoints (except /health).

Creating Users

# Create an admin user
uv run winebox-admin add admin@example.com --admin --password yourpassword

# Create a regular user
uv run winebox-admin add user@example.com --password yourpassword

# List all users
uv run winebox-admin list

# Disable/enable a user
uv run winebox-admin disable user@example.com
uv run winebox-admin enable user@example.com

# Change password
uv run winebox-admin passwd user@example.com --password newpassword

# Remove a user
uv run winebox-admin remove user@example.com

Server Management

# Start server (foreground)
uv run winebox-server start --foreground

# Start server (background)
uv run winebox-server start

# Stop server
uv run winebox-server stop

# Restart server
uv run winebox-server restart

# Check status
uv run winebox-server status

API Authentication

The API uses JWT bearer tokens. To authenticate:

  1. POST to /api/auth/token with email (in the username field per OAuth2 spec) and password (form-urlencoded)
  2. Include the returned token in subsequent requests: Authorization: Bearer <token>

Tokens expire after 24 hours.

Deployment

WineBox includes deployment scripts for Digital Ocean:

# Initial server setup
uv run python -m invoke deploy-setup --host YOUR_DROPLET_IP

# Deploy to production
uv run python -m invoke deploy

See the Deployment Guide for full instructions.

Development

Running Tests

# Run all tests
invoke test

# With verbose output
invoke test --verbose

# With coverage
invoke test --coverage

# Run without Claude Vision (save API costs)
WINEBOX_USE_CLAUDE_VISION=false invoke test

Project Structure

winebox/
├── winebox/          # Application package
│   ├── main.py       # FastAPI app
│   ├── config/       # Configuration module
│   ├── models/       # MongoDB/Beanie models
│   ├── schemas/      # API schemas
│   ├── routers/      # API endpoints
│   ├── services/     # Business logic
│   └── static/       # Web interface
├── config/           # Configuration templates
├── deploy/           # Deployment module
├── tests/            # Test suite
├── docs/             # Documentation
└── tasks.py          # Build tasks

Building Documentation

invoke docs-build
invoke docs-serve

Tech Stack

  • FastAPI: Web framework
  • MongoDB: Document database
  • Beanie: MongoDB ODM
  • fastapi-users: Authentication
  • Tesseract/Claude Vision: OCR engines
  • Vanilla JS: Frontend (no frameworks)

License

MIT License

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

winebox-0.6.81.tar.gz (7.9 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

winebox-0.6.81-py3-none-any.whl (496.6 kB view details)

Uploaded Python 3

File details

Details for the file winebox-0.6.81.tar.gz.

File metadata

  • Download URL: winebox-0.6.81.tar.gz
  • Upload date:
  • Size: 7.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for winebox-0.6.81.tar.gz
Algorithm Hash digest
SHA256 e5adde08649a242a7344d76b8735818050d03361bfb8c76c77184d1ba9219a44
MD5 debd9a70f2eade40b8b5a34e06873315
BLAKE2b-256 e282f9ade7decdf1470a8ab03d09441a2f6c1962c778111e50e4b3f9b29cbc5e

See more details on using hashes here.

Provenance

The following attestation bundles were made for winebox-0.6.81.tar.gz:

Publisher: publish.yml on jdrumgoole/winebox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file winebox-0.6.81-py3-none-any.whl.

File metadata

  • Download URL: winebox-0.6.81-py3-none-any.whl
  • Upload date:
  • Size: 496.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for winebox-0.6.81-py3-none-any.whl
Algorithm Hash digest
SHA256 bcfaa38fbed48968d7486cca8e4cf7ebb266a244e28eee64c97bed30ad0fee6e
MD5 fca88481b97e87c3651e7ff3da7f69dc
BLAKE2b-256 ee81a18b2432c3ce5474e6c779f9e2d0ff9c459abfe4320b29f13f86f478b87c

See more details on using hashes here.

Provenance

The following attestation bundles were made for winebox-0.6.81-py3-none-any.whl:

Publisher: publish.yml on jdrumgoole/winebox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page