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
- Python 3.11+
- MongoDB 7.0+
- Tesseract OCR (optional fallback)
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
uv run python -m invoke start --reload
# Background mode
uv run python -m invoke start-background
# Check status
uv run python -m invoke status
# Stop server
uv run python -m invoke stop
Access the Application
- Web Interface: http://localhost:8000/static/index.html
- API Documentation: http://localhost:8000/docs
- Health Check: http://localhost:8000/health
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:
./config.toml- Project root (development)~/.config/winebox/config.toml- User config/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
- Navigate to the Check In page
- Upload front label image (required)
- Optionally upload back label image
- Review/edit auto-detected wine details
- Set quantity and add notes
- Click "Check In Wine"
Check Out Wine
- Go to the Cellar view
- Click "Check Out" on a wine card
- Enter quantity to remove
- Add optional notes (tasting notes, occasion)
- 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:
- POST to
/api/auth/tokenwith email (in theusernamefield per OAuth2 spec) andpassword(form-urlencoded) - 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
uv run python -m invoke test
# With verbose output
uv run python -m invoke test --verbose
# With coverage
uv run python -m invoke test --coverage
# Run without Claude Vision (save API costs)
WINEBOX_USE_CLAUDE_VISION=false uv run python -m invoke test
Project Structure
winebox/
├── winebox/ # Application package
│ ├── main.py # FastAPI app
│ ├── config/ # Configuration module
│ ├── models/ # MongoDB document 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
uv run python -m invoke docs-build
uv run python -m invoke docs-serve
Tech Stack
- FastAPI: Web framework
- MongoDB: Document database
- PyMongo (async): MongoDB driver
- fastapi-users: Authentication
- Tesseract/Claude Vision: OCR engines
- Vanilla JS: Frontend (no frameworks)
License
MIT License
1 maintainer
Metadata
1 maintainer
Release files for winebox 0.7.85
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| winebox-0.7.85.tar.gz | 4.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| winebox-0.7.85-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 6.0 MB
Release files / winebox-0.7.85.tar.gz
| Download URL | winebox-0.7.85.tar.gz |
|---|---|
| Size | 4.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4de6fd772d1d1830e8b21567f73bd2bd75f4483abf11156a962013c210a229bd
|
|
BLAKE2b-256 checksum How to use checksums |
92d3c59ceeba9f773f03c3a84dd6ac611cce431ded79d12b2d4bed5b341057c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 17, 2026.
Transparency logRelease files / winebox-0.7.85-py3-none-any.whl
| Download URL | winebox-0.7.85-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2154ea8b44264d0ad48fd34bf87db88f37c4eb04246c01781b09bc10a54a8864
|
|
BLAKE2b-256 checksum How to use checksums |
7bc55d9fe06475bc4d7832959183604c56ff82d547cc047d1766f65bcc2bac31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 17, 2026.
Transparency log
